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Preface 



The DECnet-RSX Programmer's Reference Manual explains DECnet programming 
concepts and describes the DECnet-RSX calls provided for the following program- 
ming functions: 

• Intertask communication 

• Remote file access 

• Task control 

• Direct line access (DLX) 

DECnet-RSX supports intertask communication calls for MACRO-11, FORTRAN 
77, COBOL, and BASIC-PLUS-2 programming, remote file access calls for FOR- 
TRAN 77, COBOL, and BASIC-PLUS-2, task control calls for FORTRAN 77, and 
QIO calls for the DLX user interface. 

Intended Audience 

This manual is intended for users responsible for writing network programs to be run 
on DECnet-llM, DECnet-llM-PLUS, DECnet-llS, and DECnet-Micro/RSX sys- 
tems. 

Structure of This Manual 

This manual is organized into four chapters: 

Chapter 1 Provides introductory information about intertask communication, re- 
mote file access, and task control operations. 

Chapter 2 Describes the DECnet-RSX MACRO-11 programming facilities for 
intertask communication macros. 

Chapter 3 Describes the DECnet-RSX FORTRAN, COBOL, and BA- 
SIC-PLUS-2 programming facilities for intertask communication, re- 
mote file access, and FORTRAN task control. 

Chapter 4 Describes the DECnet-RSX Direct Line Access Controller program- 
ming facilities for tasks using Ethernet and non-Ethernet QIO calls. 
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The following programming examples are included in this manual and in your tape 
disk kit: 

• MACRO-11 Intertask Communication Programming Example (Transmit) 

• MACRO-11 Intertask Communication Programming Example (Receive) 

• FORTRAN Intertask Communication Programming Example (Transmit) 

• FORTRAN Intertask Communication Programming Example (Receive) 

• COBOL Intertask Communication Programming Example (Transmit) 

• COBOL Intertask Communication Programming Example (Receive) 

• BASIC-PLUS-2 Intertask Communication Programming Example (Transmit) 

• BASIC-PLUS-2 Intertask Communication Programming Example (Receive) 

• FORTRAN Remote File Access Programming Example (Append) 

• FORTRAN Remote File Access Programming Example (Read/Write) 

• COBOL Remote File Access Programming Example (Append) 

• COBOL Remote File Access Programming Example (Read/Write) 

• BASIC-PLUS-2 Remote File Access Programming Example (Append) 

• BASIC-PLUS-2 Remote File Access Programming Example (Read/Write) 

• FORTRAN Task Control Programming Example 

• DLX QIO Transmit Programming Example (for non-Ethernet device) 

• DLX QIO Receiver Programming Example (for non-Ethernet device) 

• DLX QIO Programming Example (for Ethernet device) 



This manual also contains the following appendixes: 

Appendix A Contains the network disconnect or reject reason codes. 

Appendix B Defines the Digital object type code values. 

Appendix C Provides a summary of remote file access error/completion codes. 

Appendix D Contains the MACRO-11 connect block offset and code definitions. 

Appendix E Contains the FORTRAN, COBOL, and BASIC-PLUS-2 network 
error/completion codes. 

Appendix F Contains the MACRO-11 network error/completion codes. 



Associated Documents 

Users of this manual should have the following Digital documents available for refer- 
ence: 

• Introduction to DECnet 

• DECnet-RSX Network Management Concepts and Procedures 

• DECnet-RSX Guide to Network Management Utilities 

• DECnet-RSX Guide to User Utilities 

Users of this manual should also have the RSX-11M documentation set and the 
appropriate language manuals. 
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Graphic Conventions 

In addition to the graphic conventions listed below, this manual contains specific 
conventions not defined here. Chapter 2 provides specific conventions for MACRO-11 
calls. Chapter 3 provides specific conventions for FORTRAN, COBOL, and BA- 
SIC-PLUS-2 calls. See Sections 2.2 and 3.6 for these conventions. 

CALL CLSNFW Capital letters in a command line represent characters that must 

be typed as shown. 

Italicized lowercase letters represent variables for which you must 
supply specific information. 

The use of ellipses means that not all the information the system 
would display in response to a particular command or message is 
shown or that not all the information a user would enter is shown. 



The expression (ctrl/x) refers to a control character keying sequence. 
Press the key labeled CTRL and the appropriate character key 
simultaneously when you see this symbol. 



The following acronyms are used in this manual: 



AST Asynchronous system trap 

CEX Communications Executive 

DLX Direct Line Access Controller 

FCS-11 File Control System 

MOP Maintenance Operation Protocol 

NETFOR.OLB DECnet high-level language library 

MCTI ID A/I I a nun ± AJAnpn -it 1:1 . 

NFAR Network File Access Routine 

PSW Processor status word 

QIO Queued input/output call 



(lun, status) 
PRSIZ=5 



CALL BFMT1 



Acronvms 
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1 

Introduction 



DECnet-RSX software extends the RSX-11M/11M-PLUS/11S operating systems for 
the PDP-11. With DECnet-RSX you can write programs that exchange data with 
programs running on other DECnet systems in the network, even though these sys- 
tems may run under operating systems other than RSX. This manual describes the 
network programming functions available using the MACRO-11, FORTRAN 77, CO- 
BOL, and BASIC-PLUS-2 languages. 

Before proceeding, you should become familiar with the Introduction to DECnet for 
background information. Also refer to the DECnet-RSX Guide to User Utilities for 
terminal user information. 

For programs using DECnet-RSX, tasks running on different nodes can exchange 
data using intertask communication, remote file access, or remote task control. 

• Intertask communication. User tasks on different nodes can exchange messages 
and data by issuing a series of DECnet communications calls. The DECnet software 
allows you to perform task-to-task communication regardless of the programming 
language used or the operating system running on the different nodes. For example, 
an RSX FORTRAN-77 program can communicate with a VMS program written in 
BASIC-PLUS-2. 

• Remote file access. Remote file access programs allow you to access sequential 
files for reading, writing, and appending records to remote files. User tasks can 
delete files from devices on remote nodes as well. 

When the remote node is an RSX node, programming remote file access operations 
is similar to programming local I/O operations. When the remote node is other than 
an RSX node, an accessing program can perform only those functions that its source 
language provides and that the remote file system supports. Refer to the Introduc- 
tion to DECnet for the possible file operations for different DECnet systems. 
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• Remote task control. A user can write a FORTRAN program to control the execu- 
tion of installed tasks on remote RSX or IAS DECnet nodes. The user can cause 
immediate execution of a task, schedule a task for execution at a later time, sched- 
ule a task for periodic execution, abort a task, or cancel scheduling of a task on a 
remote node. 

Functions performed by cooperating local and remote nodes can also be performed at 
the local node. For example, a task can issue MACRO-11 DECnet calls to exchange 
data with another task on the same node. This allows programmers to debug RSX 
programs locally before running them at a remote node. 

1.1 Intertask Communication Conventions 

This manual refers to calls by their first three letters. These calls are common to all 
four languages DECnet-RSX supports. The term macro refers to MACRO-11 calls, 
and the term call refers to the higher level languages. Each call name concludes with a 
lowercase x, which represents the variable portion of each call (determined by the 
programming language used). When you issue a call in MACRO-11, replace the 
variable x with a $. When you issue a call in FORTRAN, COBOL, or BA- 
SIC-PLUS-2, replace the x with NT. Lowercase x is used throughout this chapter to 
discuss intertask communication calls in a general way. 

Example: 

OPNx (generic representation) 
OPN$ (MACRO-11) 

OPNNT (FORTRAN, COBOL, or BASIC-PLUS-2) 

OPNx is the first DECnet call a task issues for any DECnet session. A session includes 
all intertask communication calls issued between the OPNx call and the CLSx call. 

Table 1-1, at the end of Section 1.2.10, provides an alphabetical list of the DECnet 
intertask communication calls, gives the function of each call, and briefly describes 
the normal or expected result after executing each call. 

1.2 Intertask Communication Concepts 

Intertask communication concepts include: 

• Establishing an active network task 

• Establishing a logical link 

• Building a connect block 

• Getting data from the network data queue 

• Sending and receiving messages 

• Sending interrupt messages 

• Checking completion status information 

• Terminating activity on a logical link 

• Closing a network connection 



1-2 



DECnet-RSX Programmer's Reference Manual 



1.2.1 Establishing an Active Network Task 



Before any task can exchange data using intertask communication calls, the task 
must be an active network task. A task is active if it is running and it has issued an 
open (OPNx) call (see Section 1.1). An OPNx call establishes a network data queue 
for a task and connects the task to the network. 

1.2.2 Assigning Logical Unit Numbers 

The following calls use a logical unit number (LUN) assigned to the network data 



queue: 




OPN$ 


Access the network 


SPA$ 


Specify a user AST routine 


GND$ 


Get network data 


REJ$ 


Reject a logical link request 


CLS$ 


End a task's network operations 


GLN$ 


Get local node information 



You can assign the LUN by defining it either as the global symbol .MBXLU in your 
program or as a parameter for the macro call. The .MBXLU definition and the macro 
call parameter definition are mutually exclusive (.MBXLU is referenced only if the 
LUN argument is left blank in the macro parameter block). You should define a 
particular network data queue LUN in one place only. 

If you use the .MBXLU definition, you can assign the LUN at assembly time or at 
task build time using one of the following command techniques: 

1. To include the logical unit number (LUN) locally in your source code, include the 
following in each source module: 

.MBXLU=x 

The variable x is an integer representing the logical unit number. 

2. Each source module in the user task must have the same integer x defined for 
.MBXLU; otherwise, the macros will complete with a privilege error (IE.PRI). 
You can define a global definition (==) by including the following statement in a 
single source module: 

.MBXLU==x 

This statement causes the task builder to define references to .MBXLU in all 
modules of your program to the value of x. 

3. If you want to defer definition of .MBXLU to task build time, you can issue the 
following task build option: 

GBLDEF= .MBXLU : x 

This option instructs the task builder to define all global references to .MBXLU 
as the value of x. 
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NETWORK ISSUES 
REJECT CALL 



ACCEPT 



TASK ISSUES 
ACCEPT CALL 



LOGICAL LINK 
ESTABLISHED 



^ END^ 



Figure 1-1: Establishing a Logical Link 
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These three command techniques for defining .MBXLU are mutually exclusive. If you 
do not use any of these procedures, the task builder returns an undefined reference 
warning message. If you run the task and ignore the warning, the six macro calls 
(OPN$, SPA$, GND$, REJ$, CLS$, and GLN$) will be rejected by the operating 
system with a directive status error indicating an invalid logical unit number. The 
task builder causes undefined references to default to 0. .MBXLU cannot be defined 
with a value because is an invalid logical unit number. 

All network logical unit numbers are freed and the task's logical links are aborted 
when you issue a CLS$ call to terminate network operations for a MACRO- 11 task. 
The CLS$ call can be issued in any of the three CLS$ formats - CLS[W]$, CLS[W]$E, 
and CLS[W]$S. 

If a LUN is not assigned to NS, any network directive will be returned with a status of 
illegal function code. 

1.2.3 Establishing a Logical Link 

To exchange data, a logical link must be established between two active network 
tasks. A logical link is a logical path between two cooperating tasks. These tasks must 
agree to communicate. When the link is established, a user task can send and receive 
messages. Figure 1-1 illustrates the flowchart process for establishing a logical link. 

The task requesting to establish a logical link is called the source task. The other task 
is called the target task. This distinction applies only during the connection sequence. 
Once the logical link is established, the terms source and target have no significance, 
since both tasks have equal access to the logical link. 

Tasks at either end of the link must specify a logical unit number (LUN) for the link. 
The LUN is the number each task assigns to the logical link so that the link can be 
associated by the tasks and the network. The tasks at both ends of the link do not 
have to use the same LUN for a link. 

1.2.4 Building a Connect Block 

Before the source task can issue a request to connect to another task, it must build a 
connect block. A connect block contains a destination descriptor, a source descriptor, 
access control information, and optionally, user-supplied data. 
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1.2.4.1 Destination Descriptor — When one task communicates with another task, 
the tasks are considered to be two objects communicating. There are two kinds of 
objects: named objects and numbered objects. The destination descriptor identifies 
the destination task either by task name or by object type number. 

Named objects are installed user-defined tasks that are referred to by name when a 
connection is requested. The object type numeric identifier for user tasks referred to 
by name is 0. 

Numbered objects are installed user-defined tasks and installed DECnet tasks that 
are referred to by object type number when a connection is requested. The object type 
numeric identifier for these tasks referred to by number ranges from 1 to 255. Num- 
bers from 1 to 127 are reserved for DECnet tasks. Numbers from 128 to 255 are 
reserved for user tasks. 

For information on defining objects, see the DECnet-RSX Network Management 
Concepts and Procedures manual. 

1 .2.4.2 Source Descriptor — The source descriptor contains information supplied 
by the DECnet software on the source node. It contains the source node name and 
either the source task name if it is a named object or the source task object number if 
it is a numbered object. The target task can use this information to determine if it 
wants to establish communications or not. 

1.2.4.3 Access Control Information — Access control information contains argu- 
ments that define your access rights at the remote node. Access control verification is 
performed according to the conventions of the target system. If the target node is 
equipped to do so, it verifies access control information before the connect request is 
passed to the target task. For information on access control verification, see the 
DECnet-RSX Network Management Concepts and Procedures manual. 

1.2.4.4 Optional Data Messages — When the source task issues a connect request, 
you can include a data message of up to 16 characters in the connect block. If the 
connect (CONx) call contains the location and length of a block of user data, the 
source node appends that block to the connect block. 

1.2.5 Getting Data from the Network Data Queue 

Once a task is connected to the network, it has a network data queue. The software on 
the connected task's node places all incoming connect request messages, interrupt 
messages, user disconnect messages, user abort messages, and network abort mes- 
sages on the task's network data queue. To get these messages, the task must issue a 
get network data (GNDx) call. A task should begin monitoring its network data queue 
as soon as the open call completes successfully. 
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The get network data call ordinarily returns the first message on the queue on a first- 
in, first-out basis. However, the GNDx call has the following options: 

• Remove the first message on the queue and place it in the message buffer. 

• Remove the first message of a specified type for any logical link and place it in the 
message buffer. 

• Remove the first message for a specified logical link regardless of the message type 
and place it in the message buffer. 

• Remove the first message of a specified type for a specified logical link and place it 
in the message buffer. 

• Determine the type, length, and associated logical link of any message on the queue 
without removing it from the queue. This allows you to assign an appropriate buffer 
size in a subsequent GNDx call that performs one of the above four options. 

1.2.6 Sending and Receiving Messages 

Once a logical link has been established between two tasks, both tasks can send and 
receive messages. DECnet distinguishes between data and nondata messages. Data 
messages are delivered directly to a buffer provided by the receiving task. Nondata 
messages are delivered to a task's network data queue. Nondata messages are unsoli- 
cited high priority messages that inform the receiving task of some event such as an 
interrupt or disconnect request. 

To send a data message, a task issues a send (SNDx) call. In the send call, specify the 
LUN assigned in the connect or accept call. Also specify the location and length of the 
data message buffer. A send call completes when the receiving node acknowledges to 
the sending node that it received a message correctly. 

To receive a data message, a task issues a receive (RECx) call. In the receive call, 
specify the LUN assigned in the connect or accept call. Also specify the location and 
length of the data message buffer. A receive call completes when the data message is 
placed in the specified data message buffer. If the data message buffer is not large 
enough, the receive call completes with a data overrun condition and the excess data 
is lost. In the case of overrun, the I/O status indicates this. To receive the next data 
message, another receive call is required. 

To send a high priority nondata message, a task issues an abort (ABTx), disconnect 
(DSCx), or interrupt (XMLe) call. 

To receive a high priority nondata message, a task issues a get network data (GNDx) 
call. 

For more information on sending and receiving messages, see Sections 3.7.15 and 
3.7.13. 
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1.2.7 Sending Interrupt Messages 



A task can send interrupt messages to another task. Usually an interrupt message 
informs the receiving task of some unusual event in the sending task. An interrupt 
(XMLe) call can be up to 16 bytes long. In the interrupt call, specify the LUN 
assigned in the connect or accept call. Also specify the location and length of the 
message buffer. 

An interrupt call completes when the receiving node acknowledges to the sending 
node that it has received the message. The receiving node software places the inter- 
rupt message on the receiving task's network data queue. The receiving task must 
issue a get network data call to remove the message from the queue and place it in the 
task's message buffer. 

A task can have only one interrupt message outstanding on a logical link. Until the 
call completes, any subsequent attempt to send another interrupt message on that 
same link is returned with a specific error code in the I/O status word. 

1.2.8 Checking Completion Status Information 

Each macro or call can include an argument specifying the address of a 2- word status 
block. While this is an optional argument, you should include it. There is no other 
way to check the status of a call when it returns. Each active macro and call should 
have its own status block. The use of the same status block by concurrent I/O requests 
will produce unpredictable results. 

The first status word contains: 

• A zero if the called macro or subroutine has not completed 

• A positive value if the called macro or subroutine produced the desired results 

• A negative value if the called macro or subroutine did not produce the desired 
results 

The second status word contains further information about the completion. For exam- 
ple, in a successful data transmission, it returns the number of bytes transmitted. 
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1.2.9 Terminating Activity on a Logical Link 



Any task can terminate activity on a logical link at any time. To do so, you can issue a 
disconnect call or an abort call. A disconnect (DSCx) call terminates transmissions 
over the logical link after all data transmissions and interrupts have been sent. An 
abort (ABTx) call disconnects the logical link immediately, regardless of any mes- 
sages queued for transmission. The receiving node software places the termination 
message on the receiving task's network data queue. The receiving task must issue a 
get network data call to retrieve the message. 

In both disconnect and abort calls, you can specify the location and length of a user 
data message for the receiving task. The message can be up to 16 bytes long. 

In the disconnect call, specify the logical unit number (LUN) assigned in the connect 
or accept call. When a disconnect call is issued, the software causes all pending 
transmits for the task issuing the disconnect call to complete before disconnecting the 
logical link. During this time, the task issuing the disconnect call continues to receive 
messages. When the last message is transmitted, any remaining receive calls complete 
with an abort condition. When the link is disconnected, the LUN is freed. A task can 
use that LUN in subsequent connect or accept calls. 

In the abort call, specify the logical unit number (LUN) assigned in the connect or 
accept call. When an abort call is issued, the software immediately aborts all pending 
transmits and receives and disconnects the link. The LUN is freed and a task can use 
that LUN in subsequent connect or accept calls. 

1.2.10 Closing a Network Connection 

To close a task's network connection, issue a close (CLSx) call. The close call informs 
the software that the task no longer requires network services. This causes the soft- 
ware to purge the task's network data queue. Any active LUNs are deactivated and 
freed for use if the task subsequently issues an open (OPNx) call. 

If there is data in the task's network data queue when the close call is issued the 
following can occur: 

• If the terminating task's network data queue contains any connect requests, the 
terminating task will receive them if it subsequently issues an open call within a 
short period of time. 

• Any other type of data in the terminating task's network data queue is discarded 
(for example, interrupt, disconnect, and abort messages). 
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Table 1-1: DECnet Communication Calls Summary 



Call Function 

ABT$ Abort a logical link 

ABTNT 



ACC$ Accept a logical link re- 

ACCNT quest 



BACC Build access control in- 

formation area 



BFMTO Build a format descrip- 
BFMT1 tor block 



CLS$ Close the network con- 

CLSNT nection — end the 
task's network opera- 
tions 

CON$ Request a logical link 

CONNT connection 



CONB$$ Build a connect block 



DSC$ Disconnect the logical 

DSCNT link 



GLN$ Get local node data: 

GLNNT node name and trans- 
mission segment size 



Normal Action 

Abort is a nondata message transmitted over the logi- 
cal link. It is delivered to the receiving task's network 
data queue by the DECnet software on the receiving 
task node. 

Notification of the target task's acceptance of the log- 
ical link request is sent by the DECnet software on 
the target task node to the DECnet software on the 
source task node, which delivers it to the status block 
of the source task CON$ or CONNT call. 

No user data is transmitted over a logical link by this 
call. In a subsequent CONNT call, the contents of 
this area are delivered to the DECnet software on the 
target task node. 

No user data is transmitted over a logical link by this 
call. In a subsequent CONNT call, the contents of 
this block are delivered to the DECnet software on 
the target task node. 

No user data is transmitted over a logical link by this 
call. The close request is delivered to the DECnet 
software on the issuing task node. 

A connect request is a high priority nondata message. 
The connect request and the connect block are sent 
over the temporary logical link to the DECnet soft- 
ware on the target node. If the target task is an active 
network task, the connect request is delivered to the 
target task's network data queue. The connect block 
is delivered to a mailbox as a result of a subsequent 
get network data call (GND$ or GNDNT). 

No user data is transmitted over a logical link by this 
call. In a subsequent CON$ call the contents of this 
block are delivered to the DECnet software on the 
target task node. 

Disconnect is a nondata message transmitted over 
the logical link. It is delivered to the receiving task's 
network data queue by the DECnet software on the 
receiving task node. 

No user data is transmitted over a logical link by this 
call. The requested data is delivered to locations 
specified by arguments of the call in the issuing task. 



(continued on next page) 
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Table 1-1 (cont.): DECnet Communication Calls Summary 



Call 



Function 



Normal Action 



GND$ 
GNDNT 

OPN$ 
OPNNT 



REC$ 
RECNT 



REJ$ 
REJNT 



SND$ 
SNDNT 



SPA$ 



WAITNT 



XMI$ 
XMINT 



Get network data from 
task's network data 
queue 

Open the network con- 
nection — create the 
task's network data 
queue 

Request to receive data 
over the logical link 



Reject a logical link re- 
quest 



Request to send a data 
message over the logi- 
cal link 



Specify the location of 
a user-writen asynchro- 
nous system trap 
(AST) routine. 

Wait for the completion 
of any other DECnet 
communications call. 



Request to send an in- 
terrupt message over 
the logical link. 



No user data is transmitted over a logical link by this 
call. The requested data is delivered to the location 
specified by arguments of the call in the issuing task. 

No user data is transmitted over a logical link by this 
call. The open request is delivered to the DECnet 
software on the issuing task node. 

No user data is transmitted over a logical link by this 
call. Notification that this call completed (that is, 
that the task that issued this call received a data 
message as a result of another task issuing a DECnet 
send call) is delivered to the status block of this call 
by the DECnet software on the issuing task node. 

Notification of the target task's rejection of the logi- 
cal link request is sent over the temporary logical link 
by the DECnet software on the target task node to 
the DECnet software on the source task node, which 
delivers it to the status block of the source task CON$ 
or CONNT call. 

The data message is transmitted over the logical link 
to the DECnet software on the receiving task node for 
delivery to the area specified in a DECnet receive call 
issued by the receiving task. When the DECnet soft- 
ware has delivered the data to the receiving task, it 
sends a completion status message over the logical 
link to the DECnet software on the sending task 
node. The completion status message is delivered to 
the status block of the send call. 

No user data is transmitted over a logical link by this 
call. When a nondata message is placed on the task's 
network data queue, control is transferred to the 
AST. 

No user data is transmitted over a logical link by this 
call. Suspends task execution until a previously is- 
sued call that had the wait option specified com- 
pletes. 

Interrupt is a high priority nondata message 
transmitted over the logical link. It is delivered to the 
receiving task's network data queue by the DECnet 
software on the receiving task node. 



Introduction 



1-11 



1.2.11 Using the Wait Option 



Many macros and calls allow you to include a W in the call name. When a W is 
included in a call (GNDW$ or GNDNTW), execution of the calling task is delayed 
until the indicated call request has completed. Execution of the calling task then 
proceeds at the instruction immediately following the call. This ensures that the 
process to be performed by the macro or call completes before the task continues. 
When the wait option is not used, the call is executed asynchronously. 

NOTE 

When using the wait option in a MACRO-11 call, you must assign an 
event flag. If the event flag is not specified, the call completes as a 
normal asynchronous call. 

1.2.12 Using the AST and WAITNT Options 

Where an asynchronous system trap (AST) has been specified in a MACRO-11 call, 
the AST is executed when the call completes. In FORTRAN, COBOL, and BA- 
SIC-PLUS-2, the WAITNT call is provided to determine when a call completes 
because there is no AST available. 



1.2.13 Using the Flow Control Option 

Network programs require buffer space for temporary message storage. For example, 
buffer space is needed to keep a copy of every message that it sends over the link until 
the receiver acknowledges receipt of the message. Network programs hold buffer space 
while waiting for inbound messages to be received. 

DECnet provides flow control mechanisms to prevent the overflow of available buffer 
space. It forces synchronization between the sending and receiving tasks so that data 
is transmitted from a source task only if the target task has issued a receive call and 
has available buffer space. 

With MACRO-11 tasks, DECnet-RSX also provides a special NOFLOW option that 
disables the flow control mechanisms. The NOFLOW option can be beneficial when a 
higher level of network performance is desired. However, this option must be used 
with caution. Without flow control, a source task can send data regardless of the 
availability of a buffer at the receiving end. If the target task does not have adequate 
buffering to handle the incoming flow of data, some data segments will be discarded. 
Each time a data segment is discarded, the software must request retransmission of 
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the discarded segment, after a timeout. This significantly degrades network perform- 
ance. If you choose the NOFLOW option, adequate buffering should be maintained at 
the target task to compensate for the loss of send/receive synchronization. The com- 
municating programs should be appropriately written. 

The NOFLOW option is desirable under the following conditions: 

• Programs already have control mechanisms or acknowledgment-signaling mecha- 
nisms written into their User layer protocol. 

• The flow of data is predictable, and the program can anticipate and handle the 
flow. 

NOTE 

If you are developing network programs, you are advised not to spec- 
ify the NOFLOW option initially. Specify the NOFLOW option only 
when the communicating programs have been tested and the data 
flow between them is adequately synchronized. 

Either end of the logical link can be independently set to FLOW or to NOFLOW 
control. Set the NOFLOW control option within the CONx and ACCx calls. Flow 
control is the default. 

1.3 DECnet-RSX Remote File Access Operations 

Using DECnet-RSX remote file access facilities, you can write a FORTRAN, CO- 
BOL, or BASIC-PLUS-2 program to perform the following file access operations for 
sequential files only: 

• Open or create a remote file 

• Read and write records to a remote file 

• Append records to a remote file 

• Close, purge, or delete a remote file 

DECnet-RSX file access facilities have similar features to those of DECnet-RSX 
intertask communication facilities. 

• The file access facilities are implemented by means of calls to subroutines. 

• The task that requests file access is called the source task, and the task that accepts 
or rejects the request is called the target task. 

• Acceptance of a file access request creates a logical link between the source and 
target tasks. Then the file access process begins. 
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Incoming file access requests are translated into calls to the file system at the target 
node. The resulting file data is sent back to the accessing task. The accessing task 
then reformats the data as required by the system. Unlike intertask communication, 
the DECnet software establishes the logical link, so much of the connection process is 
transparent. After completing file access operations, the logical link is disconnected. 

A discussion of remote file access operations is provided in Section 3.8. 

1.4 DECnet-RSX Task Control 

DECnet-RSX task control allows you to write tasks in FORTRAN that perform the 
following activities: 

• Execute an installed task on a remote node according to a set schedule using the 
RUNNCW call 

• Abort an executing task on a remote node using the ABONCW call 

• Cancel a scheduled task on a remote node using the ABONCW call 

A discussion of remote task control is provided in Section 3.9. 
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2 

DECnet-RSX MACRO-11 Programming Facilities 



DECnet-RSX provides a library of MACRO-11 macros that you can use to perform 
network intertask communication. DECnet-RSX MACRO-11 programming facilities 
describe those macros and explain how to use them. 

2.1 RSX-11 Network Macro Formats 

You can use the following formats to code your macros: 

• BUILD type macro. Creates a parameter block at assembly time and is generally 
used in conjunction with an EXECUTE type macro or a DIR$ directive. 

• EXECUTE type macro. References the parameter block created with a BUILD type 
macro and executes the function requested. An EXECUTE type macro allows you 
the option of overriding parameters specified by the BUILD type macro. 

• STACK type macro. Creates a parameter block on the processor stack and executes 
the requested function. 

Examples demonstrating the use of these three macro types are provided in Section 
2.1.4. 

2.1.1 BUILD Type Macros 

The BUILD type macro is used at assembly time to create a parameter block that 
contains arguments describing the particular network function you have requested. 
Having a predefined parameter block of this sort is especially useful if you are going to 
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perform the same network operation a number of times. If you omit an optional 
parameter from this block, the macro allocates space for it anyway. This allows you to 
fill in the argument at a later time using an EXECUTE type macro. However, if you 
plan to use the EXECUTE type macro, you must include all trailing arguments in the 
BUILD type macro. 

The format for issuing a BUILD type macro is: 

label: xxx[W]$ parameter-list[,flag] 

where 

label is a symbolic name associated with the location of the parameter 

block. 

xxx is the name of a DECnet-RSX macro. 

[W] specifies that this network function will complete synchronously. 

The issuing task waits until the function completes before continu- 
ing. If you omit the W, the call completes asynchronously. 

parameter-list is a list of arguments that describe particular features of this call. 

Each parameter must be a valid argument for a .WORD or .BYTE 
MACRO-11 directive. A list of possible parameters for each macro is 
contained in the discussion of each macro. The number of argu- 
ments specified must not exceed the number specified in an EXE- 
CUTE type macro that will use this parameter block. 

flag is a symbolic name that specifies an optional subfunction of the 

network macro. 

BUILD type macros can be executed by issuing an EXECUTE type macro or a DIR$ 
macro. A DIR$ macro call pushes the address of the network function parameter block 
that you have created with the BUILD macro on the processor stack and then issues 
an EMT 377 for the Executive to execute the macro. A DIR$ macro can be written as 
follows: 

DIR$ adr,err 

where 

adr is the address of the parameter block in the format of a source operand of a 
MOV instruction. 

err is the address of an optional error routine. The C-bit in the processor status 
word (PSW) is set whenever an error is encountered. 

NOTE 

A DIR$ macro generates less code than a corresponding EXECUTE 
macro. 
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2.1.2 EXECUTE Type Macros 



The EXECUTE type macro references a network function parameter block that you 
create at assembly time with a BUILD type macro. An EXECUTE type macro allows 
you to enter parameters that override parameters that were defined when you origi- 
nally built the parameter block with a BUILD macro. 

NOTE 

All trailing arguments must be included in a BUILD type macro that 
is referenced by an EXECUTE type macro. 

Once you have redefined or specified new parameters for the call, the EXECUTE 
macro automatically executes the function requested by the call. The format for 
issuing an EXECUTE type macro is: 

xxx[W]$E label[,override-parameter-list][,flag] 

where 

xxx is the name of a DECnet-RSX macro. 

[W] specifies that this network function will complete synchronously. 

The issuing task waits until the function completes before continu- 
ing. If you omit the W, the call completes asynchronously. 

label represents one of two values: 

• The label of the BUILD type macro that supplies parameters for 
this EXECUTE macro. You can include arguments immediately 
following the label to override any parameters previously defined 
in the BUILD parameter block. 

• The label of an area of memory that will contain the parameters 
that you are currently specifying. The parameter block is built and 
the call is executed in the same macro. 

override- is a list of one or more arguments that you specify to replace param- 

parameter-list eters that were previously defined for this call using a BUILD type 
macro. Each argument in this list must be a valid source operand for 
a MOV S, label+offset MACRO-11 instruction. 

The value of a parameter can be overridden and assigned a null 
value by specifying a null value for that parameter. For example, if 
an AST is not required, the parameter should be specified as 0. 

flag is a symbolic name that specifies an optional subfunction of the 

network macro. 
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2.1.3 STACK Type Macros 

The STACK type macro creates the network function parameter block for the call on 
the processor stack and then executes the function requested. All required parameters 
must be specified when you issue this macro. Otherwise, the macro generates assem- 
bly errors. 

The format for issuing a STACK type macro is: 

xxjc[W]$S parameter-list[,flag] 

where 

xxx is the name of a DECnet-11 macro. 

[W] specifies that this network function will complete synchronously. 

The issuing task waits until the function completes before continu- 
ing. If you omit the W, the call completes asynchronously. 

parameter-list is a list of arguments that describes particular features of this call. 

The arguments can be one or more legal source operands for MOV 
S,-(SP) MACRO-11 instructions. A list of possible parameters for 
each call is contained in the discussion of each call. 

flag is a symbolic name that specifies an optional subfunction of the 

network macro. 

2.1.4 Macro Format Examples 

The following examples demonstrate the three macro types. 

label: xxx[W]§ lun,efn,status,ast,<pl,p2,...,pn> 

; Create a parameter block 
;for the call designated 
;by xxx$ using a BUILD 
;type macro. 

xxx[W]$E label 

;Issue an EXECUTE type macro 
; referencing the parameter 
; block created for label. 

xxx[W]$E label,, „,<pl,p2> 

•Jssue an EXECUTE type macro 
;and override the parameter 
;list arguments pi and p2. 

xxx[W]$S #lun,#efn,#status,#ast,<#pl,#p2> 

;Issue a STACK type macro, create 
;a parameter block on the stack, 
;and execute the call. 
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2.2 Conventions Used in this Chapter 

The following conventions are used in the macro descriptions and examples in this 
chapter: 



asterisk * 



UPPERCASE 

lowercase italic 
square brackets 



braces 



commas and 
angle brackets < > 



flags arguments that you must check for information after the 
macro completes. For example, the status argument specifies an 
array/data item where completion status information is stored 
when the macro completes. 

represent actual characters that you must enter as shown. 

indicates variables whose value you must specify. 

enclose optional data. You must specify any argument not en- 
closed by brackets. Do not type the brackets when you code a 
macro. 

Example: 

ABT[W]$ lun, [efn] , [status] , [ast] [, <out,outlen>] 

In this macro, the lun argument is required; all other arguments 
are optional. 

enclose several arguments of which you must select just one. Do 
not type the braces when you code the macro. 

Example: 

GND [ W] $ [lun, [efn] , [status] , [ast] , 



<mail,mlen> 

<mail,mlen,mask>,NT. r TY~P 
^,NT.LON 
<„raasfc>,NT.LON 



In this example, you must include one of the four argument 
strings enclosed within the braces when you code GND$. 

must be typed where shown as part of the macro format. Even if 
you omit an argument, you must include the comma that de- 
lineates its field unless no other arguments follow. 

Example: 

Basic format: 

ABT[W]$ lun, [efn] , [status] , [ast] [, <out,outlen>] 
Sample macro: 
ABT$ 5„status 

efn, ast, out, and outlen have been omitted. A comma delineates 
the field for the missing efn argument; no commas are necessary 
for the three arguments dropped at the end of the macro. 
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numbers are assumed to be octal unless followed by a decimal point. If 

the assembler default radix has been set to octal, you can desig- 
nate a decimal radix by placing a decimal point immediately 
after a number. 

Example: 

SND$S #3 »«1 »#IOSTN » »<#MAU)< »*16 ♦ > 
In this example, 16 is a decimal number. 

2.3 Intertask Communication Macros 

This section contains descriptions and usage guidelines specific to the intertask com- 
munication calls listed in Table 2-1. Before turning to these calls, you should read the 
preceding material in this chapter. If you are not familiar with intertask communica- 
tion concepts, you should also read Chapter 1 carefully before you attempt to code 
any of these calls. 

Table 2-1: Intertask Communication Macro Summary 



Macro Function 

AJtSiip /\uui u a logical iinK 

ACC$ Accept a logical link connect request 

CLS$ End a task's network operations 

CON$ Request a logical link connection 

CONB$$ Build connect block for CON$ macro 

DSC$ Disconnect a logical link 

GLN$ Get local node information 

GND$ Get data from network data queue 

OPN$ Access the network 

REC$ Receive data over a logical link 

REJ$ Reject logical link connect request 

SND$ Send data over a logical link 

SPA$ Specify a user AST routine 

XMI$ Send interrupt message over a logical link 



2-6 



DECnet-RSX Programmer's Reference Manual 



2.3.1 Common Argument Definitions 

Arguments that are commonly used in intertask communication macros are defined 
below to avoid needless repetition throughout the macro descriptions. 

• label 

has the following meanings, depending on the macro type: 

BUILD type: label is a symbolic name associated with the location of the argu- 
ment block. 

EXECUTE type: label can represent one of two values: 

The label of the BUILD macro that supplies arguments for the current EXECUTE 
macro. If desired, you can override any arguments defined in that BUILD macro by 
reentering them after label in the EXECUTE macro. 

The label of an area of memory that will contain the arguments that you specify in 
the current EXECUTE macro. 

• status 

unless noted otherwise, is the address of an optional 2-word status block that con- 
tains completion status information on return from the macro. If specified, this 
block will contain the following values when the macro completes: 

Word 0: Byte = Error/completion code (see individual macro descriptions for 
possible codes) 

Byte 1=0 

Word 1: 

• out,outlen 

defines optional user data you wish to send with certain macros. These are paired 
optional arguments; use both when specified, or omit both. 

out is the octal starting address of a buffer that contains optional user data 
you can send on some operations. 

outlen is the length in decimal bytes of the 1- to 16.-byte message you wish to 
send. 
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ABT$ 



Abort a Logical Link 

2.3.2 ABT$ - Abort a Logical Link 
Use: 

Issue ABT$ from either task to abort a logical link. ABT$ immediately aborts all 
pending transmits and receives, disconnects the link, and frees the LUN assigned 
to the logical link. When you issue ABT$, you can send 1 to 16. bytes of user data 
to the task from which you are disconnecting (see the out,outlen arguments). 

Formats: 

label: ABT[W]$ lun,[efn], [status], [ast][,<out,outlen>] 
ABT[W]$E label, [lun] , [efn], [status], [ast] [, <out,outlen>] 
ABT[W]$S lun,[efn], [status], [ast] [,<out,outlen>] 
Arguments: 
label 

specifies the location of the argument block. See definition in Section 2.3.1. 
lun 

identifies the logical link to abort. If you initiated the connection, enter the LUN 
you used in the CON$ macro. If you accepted the connection, enter the LUN you 
used in the ACC$ macro. 

* efn 

specifies an optional event flag number that is set when ABT$ completes. 

* status 

specifies completion status information on return from ABT$. See definition in 
Section 2.3.1. 

ast 

is the address of an optional user- written AST routine to be executed after ABT$ 
completes. 

out,outlen 

defines optional user data you wish to send. See definition in Section 2.3.1. 
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Error/Completion Codes: 

IS. SUC The macro completed successfully. 

IE.ABO The specified logical link has already been aborted or disconnected. 

IE.BAD The optional user data exceeds 16. bytes. 

IE.IFC LUN not assigned to NS:. 

IE.NLN No logical link has been established on the specified LUN. 

IE.NNT The issuing task is not a network task; OPN$ did not execute successfully. 

IE.SPC Invalid buffer argument; the optional user data buffer (out) is outside the user task 
address space. 
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ACC$ 



Accept Logical Link 
Connect Request 



2.3.3 ACC$ - Accept Logical Link Connect Request 
Use: 

Issue ACC$ from the target task to establish a logical link with the source task. 
When you issue ACC$, you can send 1 to 16. bytes of user data to the source task 
(see the out,outlen arguments). 

Formats: 

label: ACC[W]$ lun,[efn],[status],[ast],<mail,[mailen], 
[out, outlen) > [,NOFLO W] 

ACC [W]$E label, [lun] , [efn] , [status] , [ast] , < [mail] , [mailen] , 
[out, outlen] > [,NOFLO W] 

ACC[W]$S lun,[efn],[status],[ast],<mail,[mailen], 
[out, outlen] > [,NOFLO W] 

Arguments: 

label 

specifies the location of the argument block. See definition in Section 2.3.1. 
lun 

assigns the logical link number. Use this LUN to refer to this logical link in any 
subsequent REC$, SND$, XMI$, ABT$, or DSC$ macro. 

* efn 

specifies an optional event flag number that is set when ACC$ completes. 

* status 

specifies completion status information on return from ACC$. See definition in 
Section 2.3.1. 

ast 

is the address of an optional user-written AST routine to be executed after ACC$ 
completes. 
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mail 



is the address of the connect block sent by the source task and retrieved by 
GND$. This address is the same one that is specified for mail in GND$ (see 
Section 2.3.9). Connect block information (see Table 2-5) is needed to establish 
the connection. 

mailen 

is the length in decimal bytes of the connect block. If omitted, the value N.CBL 
(98.) is used (see Table 2-5). 

out,outlen 

defines optional user data you wish to send. See definition in Section 2.3.1. 
Flag: 

NOFLOW 

disables flow control for incoming messages (that is, messages destined for the 
task that issued ACC$). If NOFLOW is omitted, flow control is established for 
incoming messages. Either end of the link can be set independently to flow or 
noflow control. Use the NOFLOW option with caution (see Section 1.2.13). 

Error/Completion Codes: 

IS. SUC The macro completed successfully. 

IE.ABO The task that requested the connection has aborted or has requested a disconnect 
before the connection could complete. 

IE.ALN A logical link has already been established on the specified LUN. 

IE. BAD Either the temporary link address in the connect block sent by the source task is 
invalid, or the optional user data buffer length {outleri) exceeds 16. bytes. 

IE.IFC LUN not assigned to NS:. 

IE.NNT The issuing task is not a network task; OPN$ did not execute successfully. 

IE.RSU System resources needed for the logical link are not available. 

IE.SPC Invalid buffer argument; either the pending connect block {mail) or the optional 
user data buffer (out) is not word aligned, or one of them is outside the user task 
address space. 
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CLS$ 



End Task Network 
Operations 

2.3.4 CLS$ - End Task Network Operations 

Use: 

Issue CLS$ from either task to end that task's network activity, abort all its 
logical links, and free all its network LUNs. If there is data in the task's network 
data queue, the following results can occur: 

• If the queue contains any pending connect requests that arrived while the task 
was active, the calling task is rescheduled (that is, the task will receive these 
connect requests whenever it is restarted). There is a limit of one retry and a 
timeout period of approximately 15 seconds. 

• If any connect requests arrived before the task was active, they are rejected. 

• If the queue contains an interrupt message, user disconnect, user abort, or 
network abort, this data is discarded. 

Formats: 

label: CLS[W]$ [lun],[efn],[status][,ast] 
CLS[W]$E label, [lun],[efn], [status][,ast] 
CLS[W]$S [lun],[efn],[status][,ast] 
Arguments: 
label 

specifies the location of the argument block. See definition in Section 2.3.1. 

* efn 

specifies an optional event flag number that is set when CLS$ completes. 

* status 

specifies completion status information on return from CLS$. See definition in 
Section 2.3.1. 

ast 

is the address of an optional user-written AST routine to be executed after CLS$ 
completes. 
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Error/Completion Codes: 

IS. SUC The macro completed successfully. 
IE.IFC LUN not assigned to NS:. 

IE.NNT The issuing task is not a network task; OPN$ did not execute successfully. 
IE.PRI The network is not accessed on the specified LUN. 
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CONS 



Request Logical Link 
Connection 



2.3.5 CON$ - Request Logical Link Connection 
Use: 

Issue CON$ from the source task to request a logical link with the target task. 
Before you issue CON$, you must build a connect block using the CONB$$ macro 
(see Section 2.3.6). This connect block is passed to the target node when you issue 
CON$. 

When a remote system receives a connect request, it checks to see if the target 
task is currently installed and inactive. If it is, it automatically loads and ac- 
tivates the task. The target task must issue a GND$ (see Section 2.3.9) to retrieve 
the connect block information, which it evaluates to determine whether to accept 
(ACC$, see Section 2.3.3) or reject (REJ$, see Section 2.3.12) the connect request. 

You can send 1 to 16. bytes of user data to the target task and/or receive 1 to 16. 
bytes of user data from the target task when it accepts/rejects your connect 
request. 

Formats: 

label: CON[W]$ lun, [efn], [status], [ast],<conbl,[conblen], 
[out,outlen],[in,inlen] > [,NOFLOW] 

CON[W]$E lab el, [lun],[efn], [status], [ast],<conbl,[conblen], 
[out,outlen] , [in, inlen] > [,NOFLO W] 

CON[W]$S lun, [efn], [status], [ast],<conbl, [conblen], 
[out,outlen] , [in,inlen] > [,NOFLO W] 

Arguments: 

label 

specifies the location of the argument block. See definition in Section 2.3.1. 
lun 

assigns the logical link number. Use this LUN to refer to this logical link in any 
subsequent REC$, SND$, XMI$, ABT$, or DSC$ macro. 

* efn 

specifies an optional event flag number that is set when CON$ completes. 
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status 



is the address of an optional 2 -word status block that contains completion status 
information on return from CON$. If specified, this block will contain the follow- 
ing values when CON$ completes: 

Word 0: Byte = Error/completion code (see list below) 
Byte 1 = 

Word 1: Byte = Content depends on error completion code in word 0, byte (see 
list below) 
Byte 1 = 

Listed below are possible error/completion codes you can receive in word 0, byte 0, 
plus the corresponding contents of word 1, byte 0. 



Error/Completion Code 




Word 0, Byte 


Word 1 , Byte 


is. sue 


Received byte count 


Connection accepted 


(0 if no data received) 


IS.DAO 


Received byte count 


Connection accepted 


(0 if no data received) 


with data overrun 




IE.DAO 


Received byte count 


Connection rejected by 


(0 if no data received) 


user with data overrun 




IE.URJ 


Received byte count 


Connection rejected by 


(0 if no data received) 


user 




IE.NRJ 


Reason for rejection 


Connection rejected by 


(see Appendix A) 


DECnet 




All other cases 
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ast 

is the address of an optional user-written AST routine to be executed after CON$ 
completes. 

conbl 

is the address of the connect block built using CONB$$ (see Section 2.3.6). This 
block must start on an even byte (word) boundary. 

conblen 

is the length of the connect block in decimal bytes. If omitted, the argument 
N.RQL (72.) is used (see Table 2-2). 

out,outlen 

defines optional user data you wish to send. See definition in Section 2.3.1. 
in,inlen 

defines the buffer to receive optional user data from the target task. These are 
paired optional arguments; use both or omit both. If you omit these arguments 
and the target task sends user data, a data overrun status code (IS.DAO or 
IE.DAO) will be returned. 

* in is the octal address of the buffer. 

inlen is the buffer length in decimal bytes (1 to 16.). 

Flag: 

NOFLOW 

disables flow control for this end of the link. If NOFLOW is omitted, this end of 
the link is established as flow controlled. Either end of the link can be set inde- 
pendently to flow or noflow control. Use the NOFLOW option with caution (see 
Section 1.2.13). 
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Error/Completion Codes: 

IS. SUC The macro completed successfully. 

IS.DAO The macro completed successfully; the connection has been accepted, but some 
optional user data was lost (the data sent from the target task when it accepted 
your connect request). 

IE.ALN A logical link has already been established on the specified LUN. 

IE.BAD Either the optional user data buffer exceeds 16. bytes, or the field length count in 
the connect block is too large. 

IE.DAO The connection was rejected and some optional user data was lost (the data sent 
from the target task when it rejected your connect request). 

IE.IFC LUN not assigned to NS:. 

IE.NNT The issuing task is not a network task; OPN$ did not execute successfully. 

IE.NRJ The network rejected the connection (see reject reason codes in Appendix A). 

IE.PRI The local node is shutting down. No logical link can be established. 

IE.RSU System resources needed for the logical link are not available. 

IE.SPC Invalid buffer argument; either the connect block (conbl) is not word aligned, or the 
optional user data buffers (in or out) are outside the user task address space. 

IE.URJ The remote user task rejected the connection. 
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CONB$$ 



Build Connect Block 



2.3.6 CONB$$ - Build Connect Block 

Use: 

Issue CONB$$ from the source task to build a 72. -byte connect block to be passed 
to the target task when you issue CON$ (see Section 2.3.5). The connect block 
contains the node name, destination descriptor, and access control information 
required by the target task to determine whether to accept (ACC$) or reject 
(REJ$) the connect request. Figure 2-1 illustrates a sample connect block. 

Access control information comprises arguments that define your access rights at 
the remote node or process. Access control verification is performed according to 
the conventions of the target system. If the target node is equipped to do so, it 
verifies access control information before the connect request (CON$) is passed to 
the target task. (For more information on access control verification, see the 
DECnet-RSX Network Management Concepts and Procedures manual. 

NOTE 

If you have already included the correct access control information 
with an alias node name, you need not include it in the connect block. 
For more information on using aliases, refer to the DECnet-RSX 
Guide to User Utilities or to the DECnet-RSX Network Management 
Concepts and Procedures manual. 

Format: 

CONB$$ [node],[obj},[fmt, <defscrip>),[rqid},[<pass>][,accno] 
Arguments: 

NOTE 

If you must specify non-ASCII data for any of the following argu- 
ments that require ASCII data, leave the argument field blank and 
create the non-ASCII field dynamically. You can create the entire 
connect block dynamically by reserving a block of storage equal to the 
length of N.RQL (72. bytes, as shown in Table 2-2). If you do not 
include the arguments in the CONB$$ macro call, you must define 
the fields before the macro is executed. All fields can be created or 
modified during task execution by using the symbolic offsets shown in 
Table 2-2. Use the CRBDF$ call to define these symbolic offsets. 
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node 

is the name of the target node to which this connect block is directed. The name 
must have 1 to 6 alphanumeric characters, including at least 1 alphabetic charac- 
ter. 

The obj, fmt, and descrip arguments, described below, are collectively referred to 
as the destination descriptor. The destination descriptor describes formatting 
characteristics required by the target task. You must specify this information in 
order to access the task. 

obj 

is the object type of the task to which the connect request is directed. Object 
types group DECnet tasks according to the functions they perform; they are 
identified throughout the network by object type codes (see list of codes in Appen- 
dix B). Your code must be in the range of through 255 (decimal). 

NOTE 

If you are a privileged user, you can define your own object types; 
refer to the DECnet-RSX Network Management Concepts and Pro- 
cedures manual for instructions. 

fmt 

is the descriptor format type. If you specified obj as 0, use 1 for fmt; otherwise, use 
0. 

descrip 

is the target task name (1 to 16. ASCII characters). Omit this argument if you 
specified a nonzero object type. 

The rqid, pass, and accno arguments specify access control information that 
determines your access at the remote node or process. If you have already pro- 
vided this information in an alias node name for the target node, you can omit 
these arguments. 

rqid 

is the user ID (1 to 16. ASCII characters). 
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DESTINATION 
DESCRIPTOR 
FIELDS 



ACCESS 

CONTROL 

INFORMATION 



If access control 
information is not 
specified, this 
information can 
be retrieved from 
an alias definition. 



L 
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R 
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ndname: ELROND 

format 1, objtype o 
namesz 



paaawdsz 
passwd 

accnosz: (not used by RSX) 
accno: (not used by RSX) 



TW0189 



Figure 2-1: Sample Connect Block 
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pass 



is a 1 to 8. -byte password. If you are entering an ASCII password (as opposed to 
binary), precede each character of the password with an apostrophe (') and sepa- 
rate the characters with commas. For example, the password PAS should be 
entered as 'P,'A,'S. 



accno 



is your account number at the remote node or process (1 to 16. ASCII characters). 



Table 2-2: CONB$$ Connect Block Symbolic Offsets 



Symbolic 
Offset 



N.RND* 

N.RFM 

N.ROT 



N.RIDC* 

N.RID* 

N.RPSC* 

N.RPS* 

N.RACC* 

N.RAC* 

N.RQL = 72. 



Length 

(decimal 

bytes) 



2. 
16. 

2. 

8. 

2. 
16. 



Contents 

DESTINATION DESCRIPTOR 

Remote node name with trailing blanks 

Destination descriptor format type: or 1 

Destination object type: 0-255. 

Descriptor Field for Format 

18. Not used 

Descriptor Fields for Format 1 

N.RDEC* 2. Destination task name length 
(equal to or less than 16. bytes) 

N.RDE* 16. Destination task name 

ACCESS CONTROL INFORMATION 

User ID length (equal to or less than 16. bytes) 
User ID 

Password length (equal to or less than 8. bytes) 
Password 

Account number length (equal to or less than 16. bytes) 
Account number 



These symbolic offsets are guaranteed to be even (that is, word aligned). 
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DESTINATION 
DESCRIPTOR 
FIELDS 



ACCESS 

CONTROL 

INFORMATION 



If access control 
information is not 
specified, this 
information can 
be retrieved from 
an alias definition. 
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node: ELROND 

fmt: 1. obj', o 
Byte count for descriptor 

descr/p: RECVR 



Byte count for user ID 
rgid: BLOGGS 



Byte count for password 
pass: PAS 

Account number (not used for RSX) 



TW0190 



Figure 2-2: Sample Connect Block Built by CONB$$ 
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Figure 2-2 illustrates a connect block that was built as a result of executing the 
following call: 

CONB$$ ELROND tO »1 »<RECVR> »BLOGGS »< 'P»'At'S> 

This connect block will be directed to a task named RECVR on remote RSX node 
ELROND. The object type is (named object) and the descriptor format type is 1. 
The user ID is BLOGGS and the password is PAS; no account number is required for 
RSX target systems. 
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DSC$ 



Disconnect a Logical Link 

2.3.7 DSC$ - Disconnect a Logical Link 
Use: 

Issue DSC$ from either task to disconnect the logical link and free the logical unit 
number. Unlike ABT$ (see Section 2.3.2), DSC$ causes all pending transmits to 
complete before the link is disconnected. While these transmits are completing, 
the task continues to receive messages. When the last transmit has completed, all 
pending receives are aborted and IE.ABO is returned in the I/O status block for 
each one. When you issue DSC$, you can send 1 to 16. bytes of user data to the 
task from which you are disconnecting (see the out,outlen arguments). 

Formats: 

label: DSC[W]$ lun,[efn], [status], [ast][,<out,outlen>] 
DSC[W]$E label, [lun] , [efn],[status],[ast] [, <out, outlen>] 
DSC [W]$S lun, [efn] , [status] , [ast] [, <out, outlen>] 
Arguments: 
label 

specifies the location of the argument block. See definition in Section 2.3.1. 
lun 

identifies the logical link to disconnect. If you initiated the connection, enter the 
LUN you used in the CON$ macro. If you accepted the connection, enter the 
LUN you used in the ACC$ macro. 

* efn 

specifies an optional event flag number that is set when DSC$ completes. 

* status 

specifies completion status information on return from DSC$. See definition in 
Section 2.3.1. 

ast 

is the address of an optional user-written AST routine to be executed after DSC$ 
completes. 

out, outlen 

defines optional user data you wish to send. See definition in Section 2.3.1. 
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Error/Completion Codes: 

IS. SUC The macro completed successfully. 

IE.ABO The specified logical link has already been aborted or disconnected. 
IE.BAD The optional user data exceeds 16. bytes. 
IE.IFC LUN not assigned to NS:. 

IE.NLN No logical link has been established on the specified LUN. 

IE.NNT The issuing task is not a network task; OPN$ did not execute successfully. 

IE.PRI The network is not accessed on the specified LUN. 

IE.SPC Invalid buffer argument; the optional user data buffer {out) is outside the user task 
address space. 
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GLN$ 



Get Local Node 
Information 

2.3.8 GLN$ - Get Local Node Information 
Use: 

Issue GLN$ from either task to have the following local node information placed 
in the specified buffer: 

• Local node name 

You may wish to supply the local node name within a task that is to connect to 
the local node. For example, if you have a task that runs on several nodes and 
sends data to the local node, your task must supply the local node name to the 
connect block before it can establish a connection with that node. You also may 
wish to issue a GLN$ within any task that is to display the local node name. 

• Default NSP segment size (that is, the size that NSP uses to segment data 
transmitted on a logical link) 

When you know the default NSP segment size, you can use transmit buffers 
(large data buffers) most efficiently by adjusting the length of the message 
blocks to be transmitted. 

Formats: 

label: GLN[W]$ [lun],[efn], [status], [ast],<buf,buflen> 
GLN [ W] $E lab el, [km], [efn] ,[status],[ast],<buf,buflen> 
GLN[W]$S [lun], [efn], [status], [ast],<buf, bufleny 
Arguments: 
label 

specifies the location of the argument block. See definition in Section 2.3.1. 

* efn 

specifies an optional event flag number that is set when GLN$ completes. 

* status 

is the address of an optional 2-word status block that contains completion status 
information on return from GLN$. If status is specified, the contents of word 1 
depends on the error/completion code returned in word 0, byte (word 0, byte 1 is 
always 0). 
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Contents in Word 0, Byte Contents of Word 1 

IS.SUC (1) or IE.DAO (-13) Number of bytes transferred 

to the user buffer 

lE.xxx (excluding IE.DAO, 
xxx refers to 
IE.NNT, IE.PRI, 
IE.SPC) 

ast 

is the address of an optional user-written AST routine to be executed after GLN$ 
completes. 

* buf 

is the address of the buffer to contain the received data. This buffer must start on 
an even byte (word) boundary. On return from GLN$, the data is stored as 
follows: 

Length 

(in bytes) Content/Meaning 

6 Local node name in ASCII (left justified and 

filled with spaces if name is less than 6 bytes) 

2 Default NSP segment size 

buflen 

is the length of the buffer (6 or 8. bytes) to contain the received data. If you 
specify 6 bytes, only the local node name will be returned. If you specify 8. bytes, 
both the node name and the default NSP segment size will be returned. 

Error/Completion Codes: 

IS.SUC The macro completed successfully. 

IE.DAO Data overrun. The network data was longer than the specified buffer. As much data 
as fits into the buffer is transferred to it; any remaining data is lost. 

IE.IFC LUN not assigned to NS:. 

IE.NNT The issuing task is not a network task; OPN$ did not execute successfully. 
IE.PRI The network is not accessed on the specified LUN. 

IE.SPC Invalid buffer argument; the buffer specified to receive network data (buf) is out- 
side the user task address space. 
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GND$ 



Get Network Data 



2.3.9 GND$ - Get Network Data 

Use: 

Issue GND$ from either task to get data from that task's network data queue and 
store it in the specified mail buffer (see mail,mlen) . If GND$ completes success- 
fully, word 0, byte 1 of the status block identifies which of the following unsoli- 
cited message types has been stored: 

• Connect request (NT.CON) 

• Interrupt message (NT.INT) 

• User disconnect notice (NT.DSC) 

• User abort notice (NT.ABT) 

• Network abort notice (NT.ABO) 

You can use the SPA$ macro (see Section 2=3=14) to find out how many network 
data items are in the network data queue. If you issue GND$ when the queue is 
empty, GND$ completes with an error (IE.NDA) even if the GND[W] form is 
used. 



Formats: 

label: GND[W]$ [lun],[efn], [status], last], 
(<mail,mlen> 

I <mail, mlen,mask> , NT.TYP " 
\ ,NT.LON 

GND [W]$E label, [lun] , [efn] , [status] , [ast] , 



{'<mail,mlen> 
<mail, mien, mask>, NT.TYP 
,NT.LON 
<„masfe>,NT.LON 

GND[W]$S [lun], [efn], [status], [ast], 

f <mail,mlen> 

J <mail,mlen,mask>, NT.TYP 
S ,NT.LON 
[<„mask>, ,NT. LON 
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Table 2-3: Contents of Status Block after GND$ 



If GND$ completes successfully and NT.LON is not specified: 



Status Word 



Byte 



Byte 1 



Status Word 1 
Byte 



Byte 1 



is. sue 

or 

IS.DAO 
or 

IE.DAO 



IS. SUC 
or 

IE.DAO 



IS.SUC 
or 

IE.DAO 



NT.CON 
Connect request 



NT.INT 

Interrupt 

message 

NT.DSC 

User disconnect 



NT.ABT 
User abort 



NT.ABO 
Network abort 



Number of bytes 
connect block 
(see Table 2-4). 



Number of bytes (1-16) 
in optional message. If 
0, no message was 
received. 

Number of bytes (1-16) 
in optional message. If 
0, no message was 
received. 

Number of bytes (1-16) 
in optional message. If 
0, no message was 
received. 

Reason for network 
abort (see codes in Ap- 
pendix A). 



Access verification (1) and privi- 
leged code: 

VS.NPV = Requesting user is 
nonprivileged. 



VS.PRV = 
privileged. 



Requesting user is 



VZ.NVD = Verification was not 
done. (2) 

VE.FAI = Verification failed. (3) 

LUN over which the interrupt 
message was received. 



LUN over which the user discon- 
nect message was received. 



LUN over which the network 
abort message was received. 



LUN over which the notice was 
received. 



If GND$ completes successfully and NT.LON is specified: 



Status Word 
Byte Byte 1 



Status Word 1 
Byte 



Byte 1 



IS.SUC NT.XXX 

or (type of first item 

IE.DAO in queue) 



Number of bytes in 
first item in network 
data queue. 



(continued on next page) 
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Table 2-3 (cont.): Contents of Status Block after GND$ 

If GND$ completes with an error other than IE.DAO (-13): 

Status Word Status Word 1 

Byte Byte 1 Byte Byte 1 

IE.XXX 



1. If access verification is enabled for the target node, it evaluates access control data in the 
connect request before it is allowed to pass to the target task's network data queue. For 
more information on access control, refer to the DECnet-RSX Network Management Con- 
cepts and Procedures manual. 

2. Either the verification task was not installed on the target node, or it was set to OFF with 
the NCP SET EXECUTOR VERIFICATION command or the proper access control file 
was not available. 

3. Either the account is not in the system account file, the password does not match the one in 
the file, or the object is set to inspect. 

Arguments: 

label 

specifies the location of the argument block. See definition in Section 2.3.1. 
lun 

identifies the logical unit number assigned to the network data queue. Use the 
LUN you specified in OPN$. 

* efn 

specifies an optional event flag number that is set when GND$ completes. 

* status 

is the address of an optional 2- word status block that contains completion status 
information on return from GND$. The content of the status block is summarized 
in Table 2-3. 
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ast 

is the address of an optional user-written AST routine to be executed after GND$ 
completes. 

mail, mien 

defines the task mail buffer to receive the network data or connect block on return 
from GND$. (Connect block contents are itemized in Table 2-5.) These argu- 
ments must be specified if the NT.TYP and NT.LON flags are omitted. 

* mail is the octal address of the buffer, which must start on an even byte 
(word) boundary. 

mien is the length of the buffer in decimal bytes (98. to 116.). 

mask 

specifies data type to be selected from the network data queue. Normally, GND$ 
returns items from the network data queue on a first-in, first-out basis. However, 
you can use mask to select the first item on the queue that matches the message 
type and/or LUN that you choose. Enter one of the combinations given in Table 
2-4 for the mask argument: 

Table 2-4: Mask Argument Options 



Message Type (Byte 0) 

NT.CON (connect request) 

NT.INT (interrupt message) 

NT.DSC (user disconnect) 

NT.ABT (user abort) 

NT.ABO (network abort) 

(Selects any message type on the 
specified LUN.) 



Logical Unit Number (Byte 1) 

(Selects the first LUN of message type NT.CON) 

or LUN 

or LUN 

or LUN 

or LUN 

LUN 



For example, if you want to select from the network data queue the first discon- 
nect message (NT.DSC) on LUN 3, you would code the mask argument as fol- 
lows: 3*256.+NT.DSC. 

If you specify in byte 1, the first message of the type specified in byte will be 
returned, regardless of the LUN. 
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Flags: 

NT.TYP 

indicates that a specific message type and/or LUN has been requested in a mask 
argument (see above). NT.TYP should always be used when mask is specified 
with mail and mien. 

NOTE 

If you use NT.TYP in a BUILD type GND$, you must also use it in 
any ensuing EXECUTE type GND$. 

NT.LON 

specifies dynamic assignment of mail buffer space. When you specify NT.LON, 
the message type of the first message in the network data queue is returned in 
word 0, byte 1 of the status block, and the message length is returned in word 1, 
byte 0. The message is not removed from the queue or placed in the mail buffer. If 
you specify NT.LON, you must not use mail, mien, and NT.TYP. 

NOTE 

If you use NT.LON in a BUILD type GND$, you must also use it in 
any ensuing EXECUTE type GND$. 

Figure 2-3 shows sample connect block information retrieved from the network 
data queue by a GND$ macro. The connect block shown is the one generated by 
the CONB$$ macro example given in Section 2=3=6= 

Error/Completion Codes: 

IS. SUC The macro completed successfully. 

IS.DAO The macro completed successfully, but some returned optional data was lost. 

IE.DAO Data overrun. The network data was longer than the mail buffer. As much data as 
will fit into the mail buffer is transferred to it; any remaining data is lost. 

IE.IFC LUN not assigned to NS:. 

IE.NDA There is no data in the network data queue to return. 

IE.NNT The issuing task is not a network task; OPN$ did not execute successfully. 

IE.PRI The network is not accessed on the specified LUN. 

IE.SPC Invalid buffer argument; the buffer assigned to receive network data (mail) is not 
word aligned or is outside the user task address space. 
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DESTINATION 
DESCRIPTOR 
FIELD 



SOURCE 

DESCRIPTOR 

FIELDS 



ACCESS 
CONTROL : 
NO 

VERIFICATION 



If verification is 
ON, the password is 
cleared out before 
being passed to the 
destination task 
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Symbolic Offset 

NCTL: (not used by user) 

N.SEGZ: 420 

N.0FM: 1, N.DOT: 

N.DDEC: 5 

NODE: RECVR 



NSND: BOSTON 



NSFM- 1. NSOT: 
NSDEC: 5 



NSDE: SENDR 



NCPSC- 3 
NCPS' PAS 



N.CACC: (not used by RSX) 



NCAO (not used by RSX) 



Figure 2-3: Sample Connect Block Received by GND$ 
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Table 2-5: Connect Block Received in the Mail Buffer after GND$ 

Length 
Symbolic (decimal 
Offset bytes) Contents 



N.CTL* 2. Temporary logical link address 

(required by the network; do not modify) 

N.SEGZ* 2. NSP segment size 

(used by NSP to send message data to source) 

DESTINATION DESCRIPTOR 

(20. -byte total) 

N.DFM 1. Destination descriptor format type: 0,1 

N.DOT 1. Destination object type: 0-255. 

Descriptor Field for Format 
18. Not used 

Descriptor Fields for Format 1 

N.DDEC* 2. Destination task name length 
(equal to or less than 16. bytes) 

N.DDE* 16. Destination task name 

SOURCE DESCRIPTOR 

(26. -byte total) 

N.SND* 6. Source node name 

(name of node requesting the connection; ASCII, with 
trailing blanks) 

N.SFM 1. Source descriptor format type 

(must be either format or format 1) 



These symbolic offsets are guaranteed to be even (that is, word aligned). 

(continued on next page) 
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Table 2-5 (cont.): Connect Block Received in the Mail Buffer after GND$ 



Symbolic 
Offset 



Length 

(decimal 

bytes) 



Contents 



N.SOT 



1. 



SOURCE DESCRIPTOR 

Source object type 

(object type of task or process requesting the 
connection: 1-255. for format 0, or for format 1) 

Descriptor Field for Format 

18. Not used 

Descriptor Fields for Format 1 

N.SDEC* 2. Source task name length 

(equal to or less than 16. bytes) 

N.SDE* 16. Source task name 

ACCESS CONTROL INFORMATION 

(46.-byte total) 

// no verification performed 

N.CIDC* 2. User ID length 

(equal to or less than 16. bytes) 

N.CID* 16. User ID 

N.CPSC* 2. Password length 

(equal to or less than 8. bytes) 

N.CPS* 8. Password 

N.CACC* 2. Account number length 

(equal to or less than 16. bytes) 



* These symbolic offsets are guaranteed to be even (that is, word aligned). 



(continued on next page) 



DECnet-RSX MACRO-11 Programming Facilities 



2-35 



Table 2-5 (cont.): Connect Block Received in the Mail Buffer after GND$ 

Length 
Symbolic (decimal 
Offset bvtes > Contents 

ACCESS CONTROL INFORMATION 

N.CAC* 16. Account number 

verification performed 

N.CDEV 2. Default device name 

N.CUNI 1. Default device unit number 

1, Not used 

N.CUIC 2. Log-in UIC from account file 

N.CDDS 11. Default directory string 
(0 if no default string) 

29. Not used 

OPTIONAL DATA 

(18.-byte total) 

N.CDAC* 2. Length of optional user data 

(equal to or less than 16. bytes; if no optional data) 

N.CDA* 16. Optional user data sent by source task 

(0 to 16. bytes) 

N.CBL = 98. (not including optional data) 



* These symbolic offsets are guaranteed to be even (that is, word aligned). 
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OPNS 



Access the Network 

2.3.10 OPN$ - Access the Network 
Use: 

Issue OPN$ to establish the task as an active network task and to create the task's 
network data queue. You must issue OPN$ before issuing any other intertask 
communication macro. 

Formats: 

label: OPN[W]$ [lun],[efn],[status],[ast][,<links[,lrp]>] 
OPN [W]$E label, [lun] , [efn] , [status] , [ast] [, < links [, lrp}>] 
OPN [W]$S [lun] , [efn] , [status] , [ast] [, <links[, Irp] >] 
Arguments: 
label 

specifies the location of the argument block. See definition in Section 2.3.1. 
lun 

assigns a logical unit number to the task's network data queue. You can omit this 
argument if you have already assigned the LUN to NS: by defining the symbol 
.MBXLU in the user program or in a GBLDEF option at task build time. Use this 
LUN in any subsequent GND$, SPA$, GLN$, REJ$, or CLS$ macro. 

* efn 

specifies an optional event flag number that is set when OPN$ completes. 

* status 

specifies completion status information on return from OPN$. See definition in 
Section 2.3.1. 

ast 

is the address of an optional user-written AST routine to be executed after OPN$ 
completes. 
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links 



specifies the maximum number of logical links that can be active simultaneously 
within the task. When the number of active links equals the links value (255. 
maximum), the network rejects any incoming connect request. A value of 
(which is also the default) sets no limit as long as network resources are available. 

To prevent access to your task, specify a links value of 1 and code the routine that 
processes the GND$ macro to reject all incoming connect requests. You can still 
establish outgoing links by using CON$. 

Irp 

specifies the link recovery period — that is, the number of minutes that can 
elapse from the time a physical link fails until the associated logical link is 
aborted by the network. The Irp must be in the range of through 32767(deci- 
mal). 

When specifying an Irp value, remember that unless your task has been built 
checkpointable, it will be locked in memory until the link recovery period has 
elapsed if the task has outstanding I/O when the link fails. This can cause serious 
delays for other system users who need to access the occupied area of memory. 

Error/Completion Codes: 

IS. SUC The macro completed successfully. 
IE.IFC LUN not assigned to NS:. 

IE.PRI The network is being dismounted, or the user task has already accessed the net- 
work. 

IE.RSU System resources needed for the network data queue are not available. 
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REC$ 



Receive Data over a 
Logical Link 

2.3.11 REC$ - Receive Data over a Logical Link 

Use: 

Issue REC$ from either task to receive message data over an established logical 
link and store it in a specified buffer. 

Formats: 

label: REC[W]$ lun,[efn], [status], [ast], <buf,buflen> 
REC[W]$E label, [lun], [e fri], [status], [ast][,<buf,buflen>] 
REC [ W]$S lun, [efn] , [status] , [ast] ,<buf, bufleny 
Arguments: 
label 

specifies the location of the argument block. See definition in Section 2.3.1. 
lun 

specifies the logical link over which data is to be received. If you initiated the 
connection, enter the LUN you used in the CON$ macro. If you accepted the 
connection, enter the LUN you used in the ACC$ macro. 

* efn 

specifies an optional event flag number that is set when REC$ completes. 

* status 

specifies completion status information on return from REC$. See definition in 
Section 2.3.1, and note this exception: 

Word 1: Contains number of bytes received. 

ast 

is the address of an optional user-written AST routine to be executed after REC$ 
completes. 

* buf 

is the address of the buffer to contain the received message data. 
buflen 

is the length of the receive buffer in bytes (8128. maximum). 
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Error/Completion Codes: 

IS. SUC The macro completed successfully. 

IE.ABO The logical link was disconnected during I/O operations. 

IE.DAO Data overrun. More message data was transmitted than requested. As much data as 
will fit into the receive buffer is transferred to it; any remaining data is lost. 

IE.IFC LUN not assigned to NS:. 

IE.NLN No logical link has been established on the specified LUN. 

IE.NNT The issuing task is not a network task; OPN$ did not execute successfully. 

IE.SPC Invalid buffer argument; either the data buffer (buf) is outside the user task address 
space, or the buffer length (buflen) exceeds 8128. bytes. 
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REJ$ 



Reject Logical Link 
Connect Request 

2.3.12 REJ$ - Reject Logical Link Connect Request 

Use: 

Issue REJ$ from the target task to reject a logical link connect request. When you 
issue REJ$, you can send 1 to 16. bytes of user data to the requesting task (see the 
out,outlen arguments). 

Formats: 

label. REJ[W]$ [lun],[efn], [status], [ast],<mail,[mailen] 
[,out,outlen]> 

RE J [W]$E label, [lun] , [efn] , [status] , (ast] , <mail, [maileri] 
[,out,outlen]> 

RE J [W]$S [lun] , [efn] , [status] , [ast] , <mail, [mailen] 
[,out,outlen]> 

Arguments: 

label 

specifies the location of the argument block. See definition in Section 2.3.1. 

* efn 

specifies an optional event flag number that is set when REJ$ completes. 

* status 

specifies completion status information on return from REJ$. See definition in 
Section 2.3.1. 

ast 

is the address of an optional user- written AST routine to be executed after REJ$ 
completes. 

mail 

is the address of the connect block sent by the source task and retrieved by 
GND$. This address is the same one that is specified for mail in GND$ (see 
Section 2.3.9). Connect block information (see Table 2-5) is needed to reject the 
connection. 

mailen 

is the length in decimal bytes of the connect block. If omitted, the value N.CBL 
(98.) is used (see Table 2-5). 

out,outlen 

defines optional user data you wish to send. See definition in Section 2.3.1. 
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Error/Completion Codes: 

IS. SUC The macro completed successfully. 

IE.ABO The task that requested the connection has aborted or has requested a disconnect 
before the rejection could complete. 

IE. BAD Either the temporary link address in the connect block is not valid, or the optional 
user data buffer exceeds 16. bytes. 

IE.IFC LUN not assigned to NS:. 

IE.NNT The issuing task is not a network task; OPN$ did not execute successfully. 
IE. PRE The network is not accessed on the specified LUN. 

IE.SPC Invalid buffer argument; either the connect block (mail) or the optional user data 
buffer (out) is outside the user task address space, or the connect block is not word 
aligned. 
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SND$ 



Send Data over a 
Logical Link 

2.3.13 SND$ - Send Data over a Logical Link 
Use: 

Issue SND$ from either task to send message data over an established logical link. 
This macro completes when the other task has actually received the data. 

Formats: 

label: SND[W]$ lun,[efn], [status], [ast] } <buf,buflen> 
SND [W]$E label, [lun] , [efn] , [status] , [ast] [, <buf, buflen>] 
SND [W]$S lun, [efn] , [status] , [ast] ,<buf, bufleny 
Arguments: 
label 

specifies the location of the argument block. See definition in Section 2.3.1. 
lun 

identifies the logical link over which the data is to be sent. If you initiated the 
connection, enter the LUN you used in the CON$ macro. If you accepted the 
connection, enter the LUN you used in the ACC$ macro. 

* efn 

specifies an optional event flag number that is set when SND$ completes. 

* status 

specifies completion status information on return from SND$. See definition in 
Section 2.3.1, and note this exception: 

Word 1: Contains number of bytes sent. 

ast 

is the address of an optional user-written AST routine to be executed after SND$ 
completes. 

buf 

is the address of the buffer containing the data you wish to send. 
buflen 

is the length in bytes (8128. maximum) of the data you wish to send. 
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Error/Completion Codes: 

IS. SUC The macro completed successfully. 

IE.ABO The logical link was disconnected during I/O operations. 

IE.IFC LUN not assigned to NS:. 

IE.NLN No logical link has been established on the specified LUN. 

IE.NNT The issuing task is not a network task; OPN$ did not execute successfully. 

IE.SPC Invalid buffer argument; either the message data buffer (buf) is outside the user 
task address space, or the buffer length (buflen) exceeds 8128. bytes. 
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SPA$ 



Specify User AST 
Routine 



2.3.14 SPA$ - Specify User AST Routine 
Use: 

Issue SPA$ from either task to specify a user-written AST routine to be executed 
whenever network data arrives in the network data queue. No AST routine will be 
executed for data items that arrive in the queue before SPA$ is issued. However, a 
count of all data items in the queue (including premacro entries) is returned in 
word 1 of the SPA$ status block each time SPA$ is issued. 

Formats: 

label: SPA[W]$ [lun], [efn], [status], [ast],<addr> 
SPA[W]$E label, [lun] , [efn] , [status] , [ast] [, <addr>] 
SPA[W]$S [lun] , [efn] , [status] , [ast] , <addr> 
Arguments: 
label 

specifies the location of the argument block. See definition in Section 2.3.1. 
lun 

identifies the logical unit number of the network data queue. Use the same LUN 
you assigned in the OPN$ macro. 

* efn 

specifies an optional event flag number that is set when SPA$ completes. 

* status 

specifies completion status information on return from SPA$. See definition in 
Section 2.3.1, and note this exception: 

Word 1: Contains number of items in network data queue. 

ast 

is the address of an optional user- written AST routine to be executed after SPA$ 
completes (see SPA$ programming note below). 
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addr 



is the address of a user-written AST routine to be executed whenever data arrives 
in the network data queue. (If this argument is omitted, no AST routine is exe- 
cuted.) The specified AST routine can be changed during execution of the task by 
specifying a different starting address; it can be eliminated by zeroing the starting 
address. 

NOTE 

When this AST executes, no extra information is pushed onto the 
stack (as it is for a normal completion AST). Therefore, you need not 
remove anything from the stack. 

Error/Completion Codes: 

IS. SUC The macro completed successfully. 
IE.IFC LUN not assigned to NS:. 

IE.NNT The issuing task is not a network task; OPN$ did not execute successfully. 
IE.PRI The network is not accessed on the specified LUN. 
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The following coding example shows how an application can process all network data 
at the AST level by using the SPA$ completion AST (specified by ast in the SPA$ 
macro) to simulate the network data AST. 



MAIN CODE 
□ PN$S 

3PA$S ... *CMPAST t ■ SPAAST - i Set up SPAAST as the AST entry 

5 for network data 

5 + 



5 CMPAST 
! 


- The 


entry point for 


completion of the actual SPA directme 


5 SPAAST 


- The 


entry point for 


each arrival of network data 




.ENABLE LSB 




CMPAST: 


MOV 


(SP)+ »IOSB 


i Sane the SPA$ I/O status block address 




MOU 


R » - ( S P ) 


! Sane RO 




MOU 


IOSB >R0 


i Get the I/O status address 




CMPB 


IS. SUC , (RO) 


! Was directme successful 




BNE 


20$ 


i If NE t no - just exit from AST 




MOU 


2 ( RO ) »R0 


i E 1 s e t copy current number of A S T s queued 




BEQ 


20$ 


i If EOt nothing queued* exit from AST 




BR 


10$ 


i E 1 s e t join common code 


SPAAST : 


MOU 


R » - ( S P ) 


! Sane RO 




MOM 


*1 »R0 


! Set the network data queue count to one 


10$ : 


GNDW$S 


> t > > t GNDSB 


! Get the network data item 




BC3 


20$ 


i If CS> directme failed 




CMPB 


IS. SUC t GNDSB 


5 Was the directme successful 7 




BNE 


20$ 


? If NE > no - exit from AST 








i ... do some processing ... 




SOB 


RO 1 1 0$ 


! C o n 1 1 n u e u n 1 1 1 


20$: 


MOU 


( SP ) + »R0 


i Restore RO 




ast;;$3 




5 Exit from AST 




. D3ABL 


LSB 
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XMI$ 

Send Interrupt Message 

2.3.15 XMI$ - Send Interrupt Message 
Use: 

Issue XMI$ from either task to send an interrupt message over an established 
logical link. The message you send is placed on the target task's network data 
queue and must be retrieved with a GND$ (see Section 2.3.9) before you can issue 
another XMI$ on the same logical link. (Note that XMI$ may complete before the 
target task issues a GND$ to retrieve the interrupt message.) 

Formats: 

label: XMI[W]$ lun,[efn],[status],[ast],<int,intlen> 
XMI[W]$E label, [lun] , [efn] , [status] , last] [, <int, intleny] 
XMI[W]$S lun, [efn] , [status] , [ast] , <int, intleny 
Arguments: 
label 

specifies the location of the argument block. See definition in Section 2.3.1. 
lun 

specifies the logical link over which the interrupt message is to be sent. If you 
initiated the connection, enter the LUN you used in the CON$ macro. If you 
accepted the connection, enter the LUN you used in the ACC$ macro. 

* efn 

specifies an optional event flag number that is set when XMI$ completes. 

* status 

specifies completion status information on return from XMI$. See definition in 
Section 2.3.1, and note this exception: 

Word 1: Contains number of bytes sent in message. 

ast 

is the address of an optional user- written AST routine to be executed after XMI$ 
completes. 

int 

is the address of the buffer that contains the 1- to 16. -byte interrupt message you 
wish to send. 

intlen 

is the length in decimal bytes of the message you wish to send. 
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Error/Completion Codes: 

IS. SUC The interrupt message has been transmitted successfully. (However, this code does 
not ensure that the message has been retrieved by a GND$; see Section 2.3.9). 

IE. ABO The logical link was disconnected during I/O operations. 

IE.BAD The interrupt message exceeds 16. bytes. 

IE.IFC LUN not assigned to NS:. 

IE.NLN No logical link has been established on the specified LUN. 

IE.NNT The issuing task is not a network task; OPN$ did not execute successfully. 

IE.SPC Invalid buffer argument; the interrupt message buffer (int) is outside the user task 
address space. 

IE.WLK An interrupt message was transmitted before a previous interrupt message had 
been received by the target task. 
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2.3.16 MACRO-11 Intertask Communication Programming Example 
(Transmit) 

The program SEN10 transmits 10 data messages to the cooperating program REC10. 
After SEN10 transmits and REC10 receives 10 data messages, both programs discon- 
nect from the network. 

NOTE 

This programming example is also included in your tape or disk kit. 

.TITLE SEN10 

***************************************************************** 

* * 

t THIS EXAMPLE WILL : * 

* SEND 10 DATA MESSAGES WITH THE FORMAT 'THIS IS MESSAGE N' « 

* ACCEPT A SHORT MESSAGE FROM THE INITIATING TERMINAL J 
I AND SEND THIS MESSAGE OUT AS AN 'INTERRUPT MESSAGE*. * 



To assemble use the following command string: * 

* 

MAC SEN10,SEN10/-SP-IN:[100,10]NETLIB/ML,INj[200,200]SEN10 * 

* 

To task build use the following command string: * 

« TKB SEN10,SEN10/-SP-SEN10,IN:[130,10]NETLIB/LB * 

* * 

* « 

* Mote: The IN: device must be the DECnet distribution device « 

* after the PREGEN (if any} has been performed. « 

************** ## ^ # ^ A# ^ #####A###### ******************************************* 



•MCALL 
. MCALL 
.MCALL 

DATA AREA 

MESN: .ASCII 
NUM: .ASCII 
NN= . -MESN 
PRMPT: .ASCII 
.EVEN 
IOSTN: . BLKW 
BUFF: . BLKB 
IOSTB: .BLKW 
CNT: .WORD 
ERRCNT : .WORD 
IOSB: .BLKW 

.EVEN 
CONBL: CONB$$ 



OPNW$S , CONW$S , SNDW$S , CONB$ $ , ALUN$C , QIOW$C 
EXIT$S , MRKT$C , WTSE$C , CLEF$C , SETF$C , QIO$C 
DSCW$S , XMIW$S , ASTX$S 



/THIS IS MESSAGE / 
/0/ 

/MSG:/ 
2 

16. 

2 


1 



ELROND,0,1,<REC10> 



MESSAGE TO BE TRANSMITTED 
MESSAGE NUMBER 

PROMPT FOR INTERRUPT MESSAGE 

COMPLETION STATUS FOR NETWORK 
INTERRUPT MESSAGE BUFFER 
COMPLETION STATUS FOR BUFFER 
NUM OF CHAR IN INTERRUPT MESS 
ERROR COUNT 
I/O STATUS 



; CONNECT REQUEST BLOCK 



CODE 



.EVEN 



(continued on next page) 
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START: 



OKI: 



LOOP: 



CLR 

CLEF$C 



MOVB 

ALUN$C 

ALUN$C 

OPNW$S 

TSTB 

BGT 

JMP 

CONW$S 
TSTB 
BLE 
QIO$C 



TST 

BLT 

MOV 

SNDW$S 

TSTB 

BLE 

INCB 

SOB 



ERRCNT 
5 



#60,NUM 

1, NS 

2, NS 

#1,#1,# IOSTN 

IOSTN 

OKI 

ERR1 

#2,#2,#IOSTN, , <#CONBL> 
IOSTN 
ERR2 
10. RPR, 



INITIALIZE ERROR COUNT TO ZERO 
CLEAR EVENT FLAG USED TO MAKE SURE 
INTERRUPT MESSAGE ACCEPTED PRIOR 
TO EXIT 

INITIALIZE MESSAGE NUM TO ZERO 
ASSIGN LUN 1 FOR NETWORK DATA QUEUE 
ASSIGN LUN 2 FOR LOGICAL LINK 
CREATE THE NETWORK DATA QUEUE 
TEST FOR ERRORS 



CREATE LOGICAL LINK TO "REC10' 
TEST FOR ERRORS 



5, , , I0STB,TRMAST,<BUFF,16. , ,PRMPT, 4> ; ACCEPT 

; INTERRUPT MESSAGE FROM TERMINAL 
; (USE AST) [16 CHAR MAX] 

$DSW ; TEST FOR ERRORS 

ERR3 

#10.,R0 ; SET LOOP COUNTER TO 10 

#2,#2,#IOSTN, ,<*MESN r #NN> ; SEND MESSAGE 



IOSTN 

ERR4 

NUM 

R0 r LOOP 



WTSE$C 5 



DSCW$S 
EXIT$S 



#2, #2, * IOSTN 



TERMINAL AST ROUTINE 



TRMAST: 



MOV 
MOV 
XMIW$S 



TSTB 
BLE 

SETF$C 
ASTX$S 



(SP)+,IOSB 

IOSTB+2,CNT 

#2,#3,#IOSTN, 



IOSTN 

ERR5 

5 



; TEST FOR ERRORS 

; UPDATE MESSAGE NUMBER 

; LOOP IF MORE TO SEND 

; MAKE SURE TERMINAL MESSAGE 

; HAS BEEN ENTERED 

; BEFORE EXITING 

; DISCONNECT NETWORK 

; EXIT 



; POP STACK 

; OBTAIN NUMBER OF CHARACTERS 
,<#BUFF,CNT>; TRANSMIT INTERRUPT MESSAGE 
; (NOTE USE OF EF 3 INSTEAD OF 
; EF 2 - AVOID COMPETITION) 
• TEST FOR ERRORS 

; SET EVENT FLAGE TO INDICATE 
; INTERRUPT MESSAGE SENT 
; AST EXIT 



ERROR HANDLING - A SAMPLE DEBUGGING TECHNIQUE 



DETERMINE 
WHICH 
ERROR 
OCCURRED 



ERR5: 


INC 


ERRCNT 


ERR4: 


INC 


ERRCNT 


ERR 3 : 


INC 


ERRCNT 


ERR2: 


INC 


ERRCNT 


ERR1: 


INC 


ERRCNT 




MOV 


ERRCNT, Rl 




MOV 


$DSW r R2 




MOV 


IOSTN, R3 




MOV 


IOSTN+2,R4 




IOT 





Rl CONTAINS THE ERROR NUMBER 
R2 CONTAINS THE DIRECTIVE STATUS WORD 
R3 CONTAINS THE FIRST I/O STATUS WORD 
R4 CONTAINS THE 2ND I/O STATUS WORD 
ABORT - DUMP THE REGISTERS 



.END START 
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2.3.17 MACRO-11 Intertask Communication Programming Example 
(Receive) 

Each time REC10 receives a message, from the cooperating program SEN10, it dis- 
plays THIS IS MESSAGE n on the console device (CO:). This is followed by the 
actual message. The message is sent to REC10 as an interrupt message. 

NOTE 

This programming example is also included in your tape or disk kit. 



.TITLE REC10 

*************************************************************************** » 

* * 

* * 

* THIS EXAMPLE WILL: * 

* ACCEPT SHORT MESSAGES FROM THE SENDER TASK "SNO10" * 

* 



PRINT THE MESSAGES ON THE CONSOLE DEVICE (CO:) 
DISCONNECT AND EXIT GRACEFULLY. 

To assemble use the following command string: 

MAC REC10 , REC10/-SP- IN: [ 130 , 10 ]NETL IB/ML, IN: [ 200 , 200 ]REC10 
To task build use the following command string: 

TKB REC10 ,REC10/-SP-REC10 , IN: [130 , 10 ]NETL IB/LB 



Note: The IN: device must be the DECnet distribution device 
after the PREGEN (if any) has been performed. 



* «***««*.*¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥¥*¥¥¥¥¥¥¥¥¥¥ » 

. MCALL OPNW$S , SPAW$ S , RECW$S , GNDW$S , ACCW$S , CLSW$S , NETDF$ 
. MCALL QIOW$S , ALUN$C , CLEF$C , WTSE$C , SETF$C , ASTX$S , EXIT$S 
NETDF$ 

; DATA AREA 



BUF1: 

BUF2: 

IOST: 

IOST1: 

IOST2: 

IOSB: 

ERRCNT: 

CNT: 

CNTB: 

FLAG: 



. BLKB 
.EVEN 
.BLKB 
.BLKW 
.BLKW 
.BLKW 
.BLKW 
.WORD 
.WORD 
.BLKB 
.WORD 
.EVEN 



25. 

N.CBL 

2 

2 

2 

1 





2 





BUFFER FOR NETWORK MESSAGES 
COMPLETION STATUS FOR NETWORK 
COMP. STAT. FOR GET NET DATA 
COMP. STAT. FOR ACCEPT CONNECT 
I/O STATUS 
ERROR COUNT 

USER MESSAGE CHAR COUNT 
INTERRUPT MESSAGE CHAR COUNT 
DISCONNECT FLAG 



CODE 



(continued on next page) 
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START : 


CLR 


F.RRC NT 






• T N T T T AL T ZE ERROR POI INT TO ZERO 

1111 1 X AM 1 1 1 r* DIU\vI\ V*wwl>~ A X V uuX\w 




CLEFSC 


10 . 






• CLEAR EVENT FLAG USED TO MAKE 












• SURE rOMMErT HAS OCTTIRRED 




AijUn y V— 


x f no 






• AQ^TfiM T.TTM 1 FOR NETWORK RATA OfTEIIF 




AuUnyL 


2,NS 






• ASSIGN LUN 2 FOR LOGICAL LINK 






#l,#l,#IOST 






t CREATE THE NETWORK DATA QUEUE 






IOST 






• TEST FOR ERRORS 




BLE 


ERR1 










Oxr Any O 


#!,#!,# IOST, #CMPAST,<#NETAST> ; SPECIFY AST HANDLING 




T^TH 

1 1 O 


IOST 






. TEST FOR ERRORS 




RT P 


ERR2 










WT^P.^f" 


10. 






; WAIT TO MAKE SURE CONNECT 












; HAS OCCURRED 


LOOP : 


RPfTJ^Q 
I\£A_Vf y o 


#2,#2,#IOST, 


<#BUF1,#25.: 


>; RECEIVE UP TO 25 CHARS 




TSTB 


IOST 






• TEST FOR ERRORS 




BLE 


ERR 3 










MOV 


IOST+2,CNT 






; OBTAIN CHARACTER COUNT 




QI0W$S 


#IO.WLB,#5,#5, , 


, ,<#BUF1,CNT,#40>; TYPE MESSAGE 












; ON TERMINAL 




TST 


FLAG 






; HAS DISCONNECT OCCURRED? 




BEQ 


LOOP 






; NO, POST ANOTHER RECEIVE 




CLSW$S 


#l,#l,#IOST2 






; CLOSE NETWORK 




TSTB 


IOST2 






; TEST FOR ERRORS 




BLE 


ERR5 










EXIT$S 








; PROGRAM EXIT 




BR 


LOOP 








; ERROR HANDLING - A SAMPLE 


DEBUGGING TECHNIQUE 


ERR6: 


INC 


ERRCNT 








ERR5: 


INC 


ERRCNT 








ERR4: 


INC 


ERRCNT 








ERR3: 


INC 


ERRCNT 








ERR2: 


INC 


ERRCNT 








ERR1: 


INC 


ERRCNT 










MOV 


ERRCNT r Rl 






Rl = ERROR NUMBER 




MOV 


$DSW,R2 






' R2 = DIRECTIVE STATUS WORD 




MOV 


IOST,R3 






• R3 = I/O STATUS BLOCK (1ST WORD) 




MOV 


IOST+2,R4 






• R4 = I/O STATUS BLOCK (2ND WORD) 




IOT 








ABORT - DUMP REGISTERS 


; AST 


HANDLING 


FOR DATA IN NETWORK DATA 


QUEUE 


CMP AST: 


MOV 


(SP)+,IOSB 






SAVE SPA$ I/O STATUS BLOCK \DDR 




MOV 


R0,-(SP) 






SAVE R0 




MOV 


IOSB,R0 






GET I/O STATUS BLOCK ADDRESS 




CMPB 


#IS.SUC, (R0) 






SUCCESSFUL? 




BEQ 


OKA 










JMP 


OUT 








OKA: 


MOV 


2(R0) ,R0 






GET CURRENT NETWORK DATA COUNT 




BNE 


OKB 










JMP 


OUT 








OKB: 


BR 


GET 









(continued on next page) 
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NET AST : 


MOV 


RO , - ( SP ) 


; SAVE RO 




MOV 


#1,R0 


; SET NETWORK DATA COUNT TO 1 


GET: 


GNDW$S 


#1, #l,#IOSTl, ,<#BUF2 ,#N 


CBL> ; GET NETWORK DATA 




BCS 


OUT 


; CARRY BIT SET - ERROR 




CMPB 


# IS. SUC, IOST1 


; SUCCESSFUL? 




BNE 


OUT 






CMPB 


#NT.CON, IOST1+1 


; CHECK IF CONNECT REQUEST 




BNE 


OTHER 






ACCW$S 


#2, #2,#IOST2, ,<#BUF2> 


; ACCEPT CONNECTION 




TSTB 


IOST2 


; TEST FOR ERRORS 




BLE 


ERR4 






SETF$C 


10. 


; SET EVENT FLAG TO INDICATE 








; CONNECT HAS OCCURRED 




BR 


NEXT 




OTHER: 


CMPB 


#NT.DSC, IOST1+1 


; CHECK IF DISCONNECT REQUEST 




BNE 


OTHR2 






MOV 


#1 , FLAG 


; SET DISCONNECT FLAG 




BR 


NEXT 


; GO BACK TO MAIN ROUTINE 


OTHR2 : 


CMPB 


#NT. INT, IOST1+1 


; CHECK IF INTERRUPT MESSAGE 




BEQ 


OKC 






JMP 


ERR6 


; NOT A EXPECTED COMMAND 


OKC: 


MOVB 


IOSTl+2,CNTB 


; OBTAIN CHARACTER COUNT 



QIOW$S #IO.WLB,#5,#3, , , , <#BUF2 , CNTB , # 40> ; TYPE INTERRUPT MESSAGE 

; (NOTE USE OF EF 3 



NEXT; 



QUT: 



NOP 
DEC 
BEQ 
JMP 
MOV 
ASTX$S 



RO 

OUT 

GET 

(SP)+,R0 



; INSTEAD OF EF 5) 
; CHECK IF MORE DATA 



; RESTORE RO 
; AST EXIT 



.END START 
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Programming Facilities for FORTRAN, COBOL, and 

BASIC-PLUS-2 



DECnet-RSX provides three types of network subroutines: 

• Intertask communication calls 

• Remote file access calls 

• Task control calls (FORTRAN only) 

Calls to perform these subroutines are listed in alphabetical order. The description for 
each call includes its use, formats, argument definitions, and error/completion codes. 
All references to FORTRAN pertain to both FORTRAN IV and FORTRAN-77. All 
references to BASIC pertain to BASIC-PLUS-2. Before issuing these calls, read 
Chapter 1. 

3.1 Building a DECnet-RSX Task 

When a FORTRAN, COBOL, or BASIC task uses any DECnet-RSX facility, that 
task must be linked to the library [1,1] NETFOR.OLB. For example, a COBOL task 
named FILES can be built under RSX-11M with the following task builder command 
string: 

FILES »FILES=FILES » LB : [1 ,1]NETFOR/LB ,LB : C 1 »i3C0BLIB/LB 
/ 

TA3K = F I LES 
PAR=GEN 
ACTFIL=2 
// 
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You do not have to assign logical unit numbers (LUNs) for calls to the network (NS:) 
at task build time or in your program. The LUNs are assigned to the network at run 
time by the OPNNT[W], CONNT[W], and ACCNTfW] calls. If you do assign a LUN 
to the network at task build time or in your program, this will not have an adverse 
effect on the execution of the program. Be sure that the LUNs you specify in these 
three calls are used only for network activity while they are assigned to NS:. 

3.2 Establishing a Network Task 

The first DECnet call you issue must be an open call. To access the network, issue one 
of the following open calls: 

OPNNT Establishes your task as an active network task and creates a network 
data queue for the task. 

OPNNTW Performs the same functions as OPNNT, except that further task exe- 
cution is suspended until this call completes. 

After opening the task to the network, you can establish a logical link by issuing calls 
as described in this chapter. 

To terminate network operations for a task, issue one of the following closing calls: 

CLSNT Terminates a task's network activity, aborts its established logical 
links, and frees all its network logical unit numbers. 

CLSNTW Performs the same functions as CLSNT, except that further task execu- 
tion is suspended until this call completes. 

3.3 Examining I/O Status Blocks 

All calls listed in this chapter allow you to specify the address of a status block. This 
address will contain completion status information when a call completes. 

NOTE 

The status block address is a recommended, but optional, argument 
for intertask communication and task control calls, but is a required 
argument for remote file access calls. 

Status blocks are either 1- or 2-element integer arrays/strings. One-element 
arrays/strings are used for the BACC, BFMTO, and BFMT1 calls. In these 1-element 
arrays/strings, a return of -1 indicates the arguments you supplied for the call are 
valid; a code indicates the arguments are invalid. 
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Calls other than BACC, BFMTO, and BFMT1 use 2-element arrays/strings. In a 2- 
element array/string, the first status word contains an error/completion code for the 
call. The error/completion code tells you one of the following: 

• A positive value indicates the call executed successfully. 

• A negative value indicates the call failed to execute properly. 

• A null value (0) indicates the call has not yet completed. 

Examine the value of the returned error/completion code to determine why a call 
failed. A complete list of error/completion codes is provided in Appendix E for inter- 
task calls and task control calls. 

The contents of the second status word can differ according to the call you issue. 
Therefore, each call defines the contents of the second status word. 

3.4 Using Event Flags 

The network file access routines (NFARs) require the exclusive use of two event flags. 
By default, the event flags used are 17 (.TREF) and 18 (.RCEF). You have the option 
of overriding these defaults by issuing the following commands in the task builder 
command file: 

GBLDEF=.TREF:ua/ue 
GBLDEF=.RCEF:ya/ug 

The value variable is a decimal integer from 1 to 64. (33. through 64. are global flags). 

3.5 Obtaining Access Control Information 

Access control information is generally required by the target system to prohibit 
unauthorized access to its resources. The specific information required by a target 
node should be contained in the target system's user documentation. DECnet-RSX 
nodes require you to enter user identification and a password. The following para- 
graphs describe how to supply access control information using intertask communica- 
tion, remote file access, and alias node names. 

• Intertask communication calls. If required by the target node, access control 
information is supplied by the source task user in the BACC call. 

• Remote file access calls. If required by the target node, access control informa- 
tion is supplied by the source task user in the ident argument for individual calls. 

• Alias node names. You can define an alias node name (a user-assigned logical 
name for a network node) and include access control information with the alias. 
When you exercise this option as a source task user, you do not have to specify 
access control fields in your program; the access control information supplied with 
the alias will be used automatically. More information on creating and using alias 
node names is provided in the DECnet-RSX Network Management Concepts and 
Procedures manual. 
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3.6 Conventions Used in This Chapter 



The following notation conventions are used in the call and argument descriptions 
and examples for intertask communication, remote file access, and task control calls 
in this chapter: 



asterisk * 



UPPERCASE 

lowercase italic 

commas, periods 
parentheses ( ) 



numbers 



flags arguments relating to arrays/character strings that you 
must check for information after the call completes. For exam- 
ple, the status argument specifies an array/data item where 
completion status information is stored when the call completes. 

represent actual characters that you must enter as shown. 

indicates variables whose value you must specify. 

must be typed where shown as part of the call format. Even if 
you omit an argument, you must include the comma that de- 
lineates its field unless no other arguments follow. 

FORTRAN Example: 

Basic call format: 

CALL BACC ([status], tgtblk,[usersz, user], 

[passwdsz,passwd] , [, accnosz, accno] ) 

Sample call: 

CALL BACC ( ttgtblk t t tpasswdsz,passwd) 

Status, usersz, user, accnosz, and accno have been omitted. 
Commas delineate the fields for the first three missing argu- 
ments, but are not necessary for the two arguments dropped at 
the end of the call. 

represent octal numbers in calls and examples unless followed 
by a decimal point. 

Example: 

A 1- to 43. -element character string 
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square brackets [ ] enclose optional data. You must specify any argument not en- 
closed by brackets. Do not type the brackets when you code a 
call. 

In COBOL and BASIC, you can omit an optional argument only 
if you also omit all trailing arguments. However, you can enter 
for an optional argument that you do not wish to specify, but 
that has trailing arguments you wish to include. 

COBOL Example: 

Basic call format: 

CALL "CONNT" USING lun,[status],tgtblk, 

[outsize, outmessage] , 
[insize, inmessage] . 

In this call there are three categories of optional data: 

• status 

is optional, but it cannot be omitted because it is followed by a 
required argument (tgtblk). You can enter for status if you 
do not want to have status information returned on the call. 

• outsize, outmessage 

are paired optional arguments you can omit only if you also 
omit the trailing arguments, insize and inmessage. If you do 
not want to specify outsize and outmessage, but do want to 
include the arguments that follow, you can enter null argu- 
ments (0) for outsize and outmessage. 

• insize, inmessage 

are paired optional arguments you can omit without specify- 
ing null values since there are no trailing arguments. 

Sample call: 

CALL "CONNT" USING lun,status, tgtblk tO t0 t 

insize,inmessage . 

This call specifies status and insize,inmessage, while omitting 
outsize, outmessage by specifying null values for these optional 
arguments. 
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3.7 Intertask Communication 



This section contains descriptions and usage guidelines specific to the intertask com- 
munication calls listed alphabetically in Table 3-1. 

Before turning to these calls, you should read the preceding material in this chapter. 
If you are not familiar with network intertask communication concepts, you should 
also read Chapter 1 carefully before you attempt to code any of these calls. 

Table 3-1: Intertask Communication Call Summary 



Call 


Function 


ABTNT 


Abort a logical link 


ACCNT 


Accept a logical link connect request 


BACC 


Build access control information area 


BFMTO 


Build a format destination descriptor 


BFMT1 


Build a format 1 destination descriptor 


CLSNT 


End a task's network operations 


CONNT 


Request a logical link connection 


DSCNT 


Disconnect a logical link 


GLNNT 


Get local node information 


GNDNT 


Get data from network data queue 


OPNNT 


Access the network 


RECNT 


Receive data over a logical link 


REJNT 


Reject logical link connect request 


SNDNT 


Send data over a logical link 


WAITNT 


Suspend the calling task 


XMINT 


Send interrupt message over a logical link 



Each call description includes the format for each language. The generic formats for 
each language are: 

FORTRAN: CALL XXXXX (arguments) 

COBOL: CALL "XXXXX" USING (arguments.) 

BASIC: CALL XXXXX BY REF (arguments) 
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3.7.1 Common Argument Definitions 

Arguments commonly used in intertask communication calls are defined on the fol- 
lowing pages to avoid needless repetition throughout the call descriptions. Argument 
definitions here are divided into four categories: a general category containing defini- 
tions common to all languages and three individual language categories for arguments 
with language-specific definitions. 

GENERAL 

• outsize, outmessage 

defines optional user data you want to send with certain calls. These are paired 
optional arguments; use both when specified, or omit both. 

EXCEPTION 

You cannot omit outsize, outmessage in the CONNT call in COBOL and BASIC 
unless you also omit the insize,inmessage arguments; if you want to include 
insize,inmessage, but do not want to specify outsize, outmessage, you can enter a 
null value (0) for both outsize and outmessage. (See the example under the discus- 
sion of square brackets [ ] in Section 3.6.) 

outsize specifies the length in bytes/characters of the optional user data you 
can send on some operations. It must be an integer variable or con- 
stant. 

outmessage specifies the array/string containing the user data you want to send. 

This is a 1- to 16.-element byte array for FORTRAN or a 1- to 16.- 
element numeric data item/character string for COBOL or BASIC. 

FORTRAN 

• References to integers imply single-precision integer values. 

• status 

specifies an array containing completion status information on return from the call. 
If specified, this optional 2-element single-precision integer array will contain the 
following values when the call completes: 

status(l) returns an error/completion code (see individual call descriptions for 
possible codes). 

status(2) returns a directive error code if status(l) returns a value of -40; other- 
wise, status{2) contains 0. 

• tgtblk 

specifies a 72. -element byte array where the access control information area and 
destination descriptor are built by the BACC and BFMTO or BFMT1 calls. This 
array is passed to the target task in a CONNT call. The array must start on an even 
byte (word) boundary. 
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COBOL 



• For a COBOL task using the DECnet interface, logical unit number 1 is a reserved 
number and should never be assigned for lun. 

• status 

specifies an elementary numeric data item containing completion status informa- 
tion on return from the call. If specified, this elementary numeric data item will 
contain the following values when the call completes: 

status(l) returns an error/completion code (see individual call descriptions for 
possible codes). 

status(2) returns a directive error code if status(l) returns a value of -40; other- 
wise, status(2) contains 0. 

You cannot omit status if there are trailing arguments, but you can specify for 
status if you do not want status information returned. See the discussion of square 
brackets in Section 3.6 for more information on omitting optional arguments. 

• tgtblk 

specifies a 72. -element numeric data item where the access control information area 
and destination descriptor are built by the BACC and BFMTO or BFMT1 calls. 
This is passed to the target task in a CONNT call. 

BASIC-PLUS-2 

• status%() 

specifies an array containing completion status information on return from the call. 
If specified, this optional 2-element integer array will contain the following values 
when the call completes: 

status%(0) returns an error/completion code (see individual call descriptions for 
possible codes). 

status%(l) returns a directive error code if status%(0) returns a value of -40; 
otherwise, status%{\) contains 0. 

You cannot omit status if there are trailing arguments, but you can specify for 
status if you do not want status information returned. See the discussion of square 
brackets in Section 3.6 for more information on omitting optional arguments. 

• tgtblk$ 

specifies a 72. -element character string where the access control information area 
and destination descriptor are built by the BACC and BFMTO or BFMT1 calls. 
This string is passed to the target task in a CONNT call. To allocate space for 
tgtblk%, use the STRING function: 

tgtblk%^SlTilHQ% m »0) 
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ABTNT 



Abort a Logical Link 

3.7.2 ABTNT - Abort a Logical Link 
Use: 

Call ABTNT from either task to abort a logical link. ABTNT immediately aborts 
all pending transmits and receives, disconnects the link, and frees the LUN as- 
signed to the logical link. When you call ABTNT, you can send 1 to 16. 
bytes/characters of user data to the task from which you are disconnecting (see 
the outsize, outmessage arguments). 

Formats: 

FORTRAN: CALL ABTNT [W] {lun,[status][,outsize,outmessage]) 

COBOL: CALL "ABTNT[W]" USING lun,[status][,outsize,outmessage]. 

BASIC: CALL ABTNT[W] BY REF (lun%,[status%()] 

[,outsize%,outmessage%] ) 

Arguments: 

lun 

identifies the logical link to abort. It must be an integer variable or constant. If 
you initiated the connection, enter the LUN you used in the CONNT call. If you 
accepted the connection, enter the LUN you used in the ACCNT call. 

* status 

specifies completion status information on return from ABTNT. See definition for 
your language in Section 3.7.1. 

outsize, outmessage 

defines optional user data you want to send. See definition in Section 3.7.1. 
Error/Completion Codes: 

1 The call completed successfully. 

-2 No logical link has been established on the specified LUN. 

-9 The task is not a network task; OPNNT did not execute successfully. 

-13 You are using an invalid buffer; the optional outmessage buffer is outside the user task 
address space. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-11M/M-PLUS Executive Reference Manual. 
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ACCNT 



Accept Logical Link 
Connect Request 

3.7.3 ACCNT - Accept Logical Link Connect Request 
Use: 

Call ACCNT from the target task to establish a logical link with the source task. 
When you call ACCNT, you can send 1 to 16. bytes/characters of user data to the 
source task (see the outsize, outmessage arguments). 

Formats: 

FORTRAN: CALL ACCNT[W] (lun, [status], mailbuf, 

[outsize, outmessage] ) 

COBOL: CALL "ACCNT[W]" USING lun, [status], mailbuf 

[,outsize, outmessage] . 

BASIC: CALL ACCNT[W] BY REF (lun%,[status%()],mailbuf$ 

[,outsize%,outmessage%]) 

Arguments: 

lun 

assigns the logical link number. This value must be an integer variable or con- 
stant. Use this LUN when referring to this logical link in any succeeding RECNT, 
SNDNT, XMINT, ABTNT, or DSCNT call. 

* status 

specifies completion status information on return from ACCNT. See definition for 
your language in Section 3.7.1. 

mailbuf 

specifies the 1- to rc-element array/string containing the connect block needed to 
establish the connection. In FORTRAN, this array must start on an even byte 
(word) boundary. For more information, see Table 3-2 and the description of 
mailbuf under GNDNT (Section 3.7.11). 

outsize, outmessage 

defines optional user data you want to send. See definition in Section 3.7.1. 
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Error/Completion Codes: 

1 The call completed successfully. 
-1 System resources needed for the logical link are not available. 

-3 The task that requested the connection has aborted or has requested a disconnect before 
the connection could complete. 

-5 The temporary link address in the mail buffer is not valid. 

-8 A logical link has already been established on the specified LUN. 

-9 The task is not a network task; OPNNT did not execute successfully. 

-13 You are using an invalid buffer; the mailbuf or outmessage buffer is outside the user task 
address space, or (for FORTRAN) mailbuf is not word aligned. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-11M/M-PLUS Executive Reference Manual. 
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BACC 



Build Access Control 
Information Area 



3.7.4 BACC - Build Access Control Information Area 

Use: 

Call BACC from the source task to build the access control information area for 
the connect block that will be passed to the target task when you call CONNT 
(see Section 3.7.8). Access control information comprises arguments that define 
your access rights at the remote node or process. Access control verification is 
performed according to the conventions of the target system. If the target node is 
equipped to do so, it verifies access control information before the CONNT call is 
passed to the target task. (For more information on access control verification, see 
the DECnet-RSX Network Management Concepts and Procedures manual and 
Sections 1.2.4.3 and 3.5 of this manual.) 



NOTE 

If you have already included the correct access control information 
with an alias node name, you need not call BACC. For more informa- 
tion on using aliases, refer to the DECnet-RSX Guide to User Utili- 
ties or to the DECnet-RSX Network Management Concepts and Pro- 
cedures manual. 

Formats: 

FORTRAN: CALL BACC ([status],tgtblk,[usersz,user], 

\r^n Qemrl o \ n n r>m nor* rt n nir\ r\~\ \ 

COBOL: CALL "BACC" USING [status],tgtblk,[usersz,user], 

[passwdsz,passwd] [,accnosz, accno] . 

BASIC: CALL BACC BY REF ([status%],tgtblk$,[usersz%,user$], 

[passwdsz%,passwd%][,accnosz%,accno%]) 
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Arguments: 

* status 

specifies an integer variable containing completion status information on return 
from BACC. On return, the variable is set to -1 if the BACC call completed 
successfully or to if there was an invalid BACC argument. 

In COBOL and BASIC, you cannot omit status, but you can specify for status if 
you do not want status information returned. See the discussion of square brack- 
ets in Section 3.6 for more information on omitting optional arguments. 

* tgtblk 

specifies an array/string in which the access control information area is to be 
built. See definition for your language in Section 3.7.1. 

usersz, user 

specifies the user ID. These are paired optional arguments; if you do not use both, 
you must omit both (in FORTRAN) or enter for both (in COBOL and BASIC). 
For information on omitting arguments in COBOL and BASIC, refer to the dis- 
cussion of optional arguments (square brackets []) in Section 3.6. 

usersz specifies the user ID length in bytes/characters. This field is an inte- 
ger variable or constant. 

user specifies the 1- to 16. -element array/string containing the user ID. 

passw dsz,passwd 

specifies the password that determines your access at the remote node. These are 
paired optional arguments; if you do not use both, you must omit both (in FOR- 
TRAN) or enter for both (in COBOL and BASIC). For information on omitting 
arguments in COBOL and BASIC, refer to the discussion of optional arguments 
(square brackets []) in Section 3.6. 

passwdsz specifies the password length in bytes/characters. This field is an 
integer variable or constant. 

passwd specifies a 1- to 8. -element array/string containing the password. 
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accnosz,accno 

specifies the account number. These are paired optional arguments; use both or 
omit both. 

accnosz specifies the account number length in bytes/characters (not used 
for RSX target systems). This field is an integer variable or con- 
stant. 

accno specifies a 1- to 16. -element array/string containing the account 
number. 



Connect Block Offsets 



Length (in decimal 
bytes/characters) 

26. 



2. 

16. 
2. 

8. 
2. 



Destination Descriptor 

Built by BFMTO or BFMT1 call 

(see Sections 3.7.5 and 3.7.6, respectively) 

Access Control 

User ID length 

(equal to or less than 16. bytes/characters) 
User ID 

Password length 

(equal to or less than 8. bytes/characters) 
Password 

Account number length 

(equal to or less than 16. bytes/characters) 



16. 



Account number 
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BFMTO 



Build a Format 
Destination Descriptor 



3.7.5 BFMTO - Build a Format Destination Descriptor 

Use: 

Call BFMTO from the source task to build a format destination descriptor for 
the connect block that will be passed to the target task when you call CONNT 
(see Section 3.7.8). A format descriptor is used to connect to a target task that 
requires specification of an object type only. Object types group DECnet pro- 
grams according to the functions they perform; they are identified throughout the 
network by object type codes (see Appendix B). For example, the TLK server 
task, LSN, has an object type code 016 (decimal); any other program providing 
the same function on another DECnet system, regardless of its name, would also 
be referred to using object type code 016 (decimal). 

Formats: 

FORTRAN: CALL BFMTO {[status],tgtblk,ndsz,ndname,objtype) 
COBOL: CALL "BFMTO" USING [status],tgtblk,ndsz,ndname,objtype. 

BASIC: CALL BFMTO BY REF ([status%],tgtblk$,ndsz%,ndname$, 

objtype%) 

Arguments: 

* status 

specifies an integer variable containing completion status information on return 
from BFMTO. On return, the variable is set to .TRUE, (for FORTRAN) or to -1 
(for COBOL and BASIC) if the BFMTO call completed successfully. It is set to 
.FALSE, (for FORTRAN) or to (for COBOL and BASIC) if there was an invalid 
BFMTO argument. 

In COBOL and BASIC, you cannot omit status, but you can specify for status if 
you do not want status information returned. See the discussion of square brack- 
ets in Section 3.6 for more information on omitting optional arguments. 

* tgtblk 

specifies an array/string in which the destination descriptor is to be built. See 
definition for your language in Section 3.7.1. 
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ndsz 



specifies the node name length in bytes/characters. This field must be an integer 
variable or constant. 



specifies a 1- to 6-element array/string containing the name of the node to which 
the connect request is directed. 



specifies the object type of the task to which the connect request is directed. This 
integer variable or constant must be in the range 1 through 255 (decimal). See 
Appendix B for a list of object types. 



If you are a privileged user, you can define your own object types; 
refer to the DECnet-RSX Network Management Concepts and Pro- 
cedures manual for instructions. 

Connect Block Offsets 
Length (in decimal 

bytes/characters) Destination Descriptor 

6. Destination node name with trailing blanks 



ndname 



objtype 



NOTE 



1 




1. 



Destination object type (1 to 255.) 



Descriptor Field for Format 



18. 



Not used 



Access Control 



46. 



Built by BACC call (see Section 3.7.4) 
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BFMT1 



Build a Format 1 
Destination Descriptor 

3.7.6 BFMT1 - Build a Format 1 Destination Descriptor 
Use: 

Call BFMT1 from the source task to build a format 1 destination descriptor for 
the connect block that will be passed to the target task when you call CONNT 
(see Section 3.7.8). A format 1 descriptor is used to connect to a target task that 
requires specification of a task name only. 

Formats: 

FORTRAN: CALL BFMT1 ([status],tgtblk,ndsz,ndname, 

objtype, namesz, name) 

COBOL: CALL "BFMT1" USING [status], tgtblk,ndsz,ndname, 

objtype, namesz, name. 

BASIC: CALL BFMT1 BY REF {[status%],tgtblk%,ndsz%,ndname%, 

objtype%,namesz%,name%) 

Arguments: 

* status 

specifies an integer variable containing completion status information on return 
from BFMT1. On return, the variable is set to .TRUE, (for FORTRAN) or to -1 
(for COBOL and BASIC) if the BFMT1 call completed successfully. It is set to 
.FALSE, (for FORTRAN) or to (for COBOL and BASIC) if there was an invalid 
BFMT1 argument. 

In COBOL and BASIC, you cannot omit status, but you can specify for status if 
you do not want status information returned. See the discussion of square brack- 
ets in Section 3.6 for more information on omitting optional arguments. 

* tgtblk 

specifies an array/string in which the destination descriptor is to be built. See 
definition for your language in Section 3.7.1. 

ndsz 

specifies the node name length in bytes/characters. This field must be an integer 
variable or constant. 

ndname 

specifies the 1- to 6-element array/string containing the name of the node to which 
the connect request is directed. 
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objtype 

specifies the object type to which the connect request is directed. For BFMT1, 
objtype must be 0. 

namesz 

specifies the length of the program name in bytes/characters. This field must be 
an integer variable or constant. 

name 

specifies a 1- to 16.-element array/string containing the name of the program to 
which you wish to connect. 

Connect Block Offsets 

Length (in decimal 



bytes/characters) Destination Descriptor 

6. Destination node name with trailing blanks 

1. Descriptor format type, which is 1 for BFMTl 

1. Destination object type, which is for BFMTl 

Descriptor Fields for Format 1 

2. Destination program name length 

(equal to or less than 16. bytes/characters) 

16. Destination program name 

Access Control 

46. Built by BACC call (see Section 3.7.4) 

Sample coding for BFMTl calls is given in the follow- 



ing examples. Each language-specific example shows 
the code for a BFMTl call, including the declaration 
statements. 
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FORTRAN Example: 



I NTEGER*2 I0ST(2) »NDS I Z »0B JTY » PRSIZ 

BYTE NDNAM(G) ♦ PRGNAM ( 5 ) 
BYTE C0NBLK(72) 

DATA NDNAM/ 'E ' * ' L ' * ' R ' t ' ' t ' H ' * ' D ' / 
DATA PRGNAM / ' R ' t ' E ' » ' C ' t ' ' t ' R ' / 

OBJTY=0 
ND3IZ=S 
PRSIZ=5 



♦ 

CALL BFMT1 ( I OST ♦ CONBLK » NDS I Z » NDNAM »OB JTY * PRS I Z * PRGNAM ) 

COBOL Example: 

WORKING- STORAGE SECTION* 



01 STORE-STUFF ♦ 



03 


NODNAM 


PIC 


V 
/\ 


( 6 ) VALUE " ELROND " 


03 


TSKNAM 


PIC 


X 


( 6 ) VALUE "RECUR"* 


03 


STAT 


PIC 


v 

f\ 


999 USAGE COMP* 


03 


CONBLK 


PIC 


V 
/\ 


(72) . 


03 


NLENG 


PIC 


9 


USAGE COMP. 


03 


TLENG 


PIC 


9 


USAGE COMP* 


03 


DUMMY 


PIC 




(2) ♦ 



PROCEDURE DIVISION 



(continued on next page) 



Programming Facilities for FORTRAN, COBOL, and BASIC-PLUS-2 



3-19 



##*###*####*#**###****##*###**## 
* BUILD A FORMAT 1 CONNECT BLOCK ♦ * 
####*##*#####*###*#*#******#*##* 

MOVE B TO NLENG . 
MOVE 5 TO TLENG ♦ 
CALL BFMT1 USING 

STAT 
CONBLK 

NLENG 
NODNAM 
DUMMY 
TLENG 
TSKNAM . 



BASIC-PLUS-2 Example: 

40 CONBLK* = STRING(723t fOl) 

\ NDNAM . LEN%=SI 
\ TSKNAM ♦ LEN% = 57. 
\ NDNAM*= "ELROND" 
\ T3KNAM*= "RECMR" 

\ CALL BFMT1 BY REF ( STAT3C »CONBLK$ » NDNAM . LENX » 

NDNAM* f DUMMY'* *TSKNAM . LENX » 
TSKNAM* ) 
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CLSNT 



End Task Network 
Operations 

3.7.7 CLSNT - End Task Network Operations 

Use: 

Call CLSNT from either task to end that task's network activity, abort all its 
logical links, and free all its network LUNs. If there is data in the task's network 
data queue, the following results can occur: 

• If the queue contains any pending connect requests that arrived while the task 
was active, the calling task is rescheduled (that is, the task will receive these 
connect requests whenever it is restarted). There is a limit of one retry. 

If any connect requests arrive when the task is not active, they are rejected. 

• If the queue contains an interrupt message, it is discarded. 

• If the queue contains a user disconnect, user abort, or network abort message, 
this data is ignored. 

Formats: 

FORTRAN: CALL CLSNT[W] [(status)] 
COBOL: CALL "CLSNT[W]" USING [status]. 
BASIC: CALL CLSNT[W] BY REF [(status%())] 
Arguments: 

* status 

specifies completion status information on return from CLSNT. See definition for 
your language in Section 3.7.1. 

Error/Completion Codes: 

1 The call completed successfully. 
-9 The task is not a network task; OPNNT did not execute successfully. 
-10 The network is not accessed on this LUN. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-11M/M-PLUS Executive Reference Manual. 



Programming Facilities for FORTRAN, COBOL, and BASIC-PLUS-2 



3-21 



CONNT 



Request Logical 
Link Connection 

3.7.8 CONNT - Request Logical Link Connection 
Use: 

Call CONNT from the source task to request a logical link with the target task. 
Before you call CONNT, you must build a connect block using the BACC and 
BFMTO or BFMT1 calls. The BACC call builds the access control information 
area (unless this data has already been supplied with an alias node name) and the 
BFMTO or BFMTl call builds the destination descriptor format fields. Use 
BFMTO when connecting to a task that requires only an object type; use BFMTl 
when the task requires only a task name. Refer to Sections 3.7.4 (BACC), 3.7.5 
(BFMTO), and 3.7.6 (BFMTl) for full details on each call. 

When a remote system receives a connect request, it checks to see if the remote 
task is currently installed and inactive. If it is, it automatically loads and ac- 
tivates the remote task. The connect block is passed to the remote task (see 
GNDNT, Section 3.7.11). The task evaluates the connect request and then de- 
cides to accept (ACCNT, Section 3.7.3) or reject (REJNT, Section 3.7.14) the 
request. You can send 1 to 16. bytes/characters of user data to the remote task 
and/or receive 1 to 16. bytes/characters of user data from the remote task when it 
accepts/rejects your connect request. 

Formats: 

FORTRAN: CALL CONNT[W] (lun, [status], tgtblk, 

[outsize, outmessage] , 
[insize,inmessage]) 

COBOL: CALL "CONNT[W]" USING lun,[status], tgtblk, 

[outsize, outmessage] , 
[insize, inm essage] . 

BASIC: CALL CONNT[W] BY REF (lun%,[status%Q],tgtblk§, 

[outsize%,outmessage§], 
[insize%,inmessage§]) 

Arguments: 

lun 

assigns the logical link number. This value must be an integer variable or con- 
stant. Use this LUN when referring to this logical link in any succeeding RECNT, 
SNDNT, XMINT, ABTNT, or DSCNT call. 
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* status 

specifies an array/data item containing completion status information on return 
from CONNT. In COBOL and BASIC, you cannot omit status, but you can 
specify for status if you do not want status information returned. See the 
discussion of square brackets in Section 3.6 for more information on omitting 
optional arguments. If specified, this optional 2-element integer array/data item 
will contain the following values when the call completes: 

First Status Word 

status%(0) (BASIC) or 
statusd) (FORTRAN, COBOL): 
Error/completion code (see list below). 
Second Status Word 

status%(l) (BASIC) or 
status{2) (FORTRAN, COBOL): 

Contents depends on error/completion code in first status word (see list be- 
low). 

Listed below are possible error/completion codes you can receive in the first status 
word, plus the corresponding contents of byte in the second status word. (Byte 1 of 
the second status word is always 0.) 

Error/Completion Code Contents of Byte 

First Status Word Second Status Word 

Connection accepted Received byte count 

Connection accepted Received byte count 
with data overrun 

Connection rejected by Received byte count 
user with data overrun 

Connection rejected by Reason for rejection 

DECnet (see Appendix A) 

Connection rejected by Received byte count 
user 

Directive error Directive error code 

All other cases 
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tgtblk 

specifies an array/string containing access control information area and destina- 
tion descriptor. See definition for your language in Section 3.7.1. 

outsize, outmessage 

defines optional user data you want to send. See definition in Section 3.7.1 and 
note the exception. 

insize, inmessage 

defines user data you can receive from the target task. These are paired optional 
arguments; use both or omit both. 

insize specifies the length in bytes/characters of the user data you want 

to receive. It must be an integer variable or constant. 

* inmessage specifies the array/string that will store the user data sent by the 
target task. This is a 1- to 16.-element byte array for FORTRAN 
or a 1- to 16. -element character string for COBOL or BASIC. 

Error/Completion Codes: 

1 The call completed successfully. 

2 The call completed successfully; the connection has been accepted, but some returned 
optional data was lost (the data sent to the target task when you called CONNT). 

-1 System resources needed for the logical link are not available. 

-4 The connection was rejected and some optional data was lost (the data sent to the target 
task when you called CONNT). 

-5 Either an optional user data buffer exceeds 16. bytes/characters, or the field length count 
in the connect block is too large. 

-7 The connection was rejected by the network (see reject reason codes in Appendix A) . 

-8 A logical link has already been established on the specified LUN. 

-9 The task is not a network task; OPNNT did not execute successfully. 

-12 The connection was rejected by the remote user task. 

-13 You are using an invalid buffer; the tgtblk, inmessage, or outmessage buffer is outside the 
user task address space or (for FORTRAN) tgtblk is not word aligned. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-11M/M-PLUS Executive Reference Manual. 
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DSCNT 



Disconnect a Logical Link 

3.7.9 DSCNT - Disconnect a Logical Link 
Use: 

Call DSCNT from either task to disconnect the logical link and free the logical 
unit number. When you issue a DSCNT, all pending transmits are completed 
before the link is disconnected. While these transmits are completing, the task 
continues to receive messages. When the last transmit has completed, all pending 
receives are aborted and you receive an abort status in the I/O status block for 
each one. When you call DSCNT, you can send 1 to 16. bytes/characters of user 
data to the task from which you are disconnecting (see the outsize, outmessage 
arguments) . 

Formats: 

FORTRAN: CALL DSCNT[W] (lun,[status][,outsize,outmessage}) 

COBOL: CALL "DSCNT[W]" USING lun,[status][,outsize,outmessage]. 

BASIC: CALL DSCNTfW] BY REF (lun%,[status%()], 

[outsize%,outm essage§] ) 

Arguments: 

lun 

specifies the logical link you want to disconnect. It must be an integer variable or 
constant. If you initiated the connection, enter the LUN you used in the CONNT 
call. If you accepted the connection, enter the LUN you used in the ACCNT call. 

* status 

specifies completion status information on return from DSCNT. See definition for 
your language in Section 3.7.1. 

outsize, outmessage 

defines optional user data you want to send. See definition in Section 3.7.1. 
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Error/Completion Codes: 

1 The call completed successfully. 

-2 No logical link has been established on the specified LUN. 

-5 The optional user data exceeds 16. bytes/characters. 

-9 The task is not a network task; OPNNT did not execute successfully. 

-10 The network is not accessed on this LUN. 

-13 You are using an invalid buffer; the outmessage buffer is outside the user task address 
space. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-11M/M-PLUS Executive Reference Manual. 



3-26 



DECnet-RSX Programmer's Reference Manual 



GLNNT 



Get Local Node 
Information 

3.7.10 GLNNT - Get Local Node Information 
Use: 

Call GLNNT from either task to have the following local node information placed 
in the specified buffer: 

• Local node name 

You may want to supply the local node name within a program that is to 
connect to the local node. For example, if you have a program that runs on 
several nodes and sends data to the local node, your program must supply the 
local node name to the connect block before it can establish a connection with 
that node. You also may want to issue a GLNNT within any program that is to 
display the local node name. 

• Default NSP segment size (that is, the size that NSP uses to segment data 
transmitted on a logical link) 

When you know the default NSP segment size, you can use transmit buffers 
(large data buffers) most efficiently by adjusting the length of the message 
blocks to be transmitted. 

Formats: 

FORTRAN: CALL GLNNT[W] ([status], buflen,buf) 
COBOL: CALL " GLNNT [W]" USING [status], buflen,buf. 
BASIC: CALL GLNNT [W] BY REF {[status%i)],buflen%,buf%) 
Arguments: 

* status 

specifies completion status information on return from GLNNT. See definition 
for your language in Section 3.7.1. 

buflen 

specifies an array/string containing the received data length. If you specify 6 
bytes/characters, only the local node name will be returned. If you specify 8. 
bytes/characters, both the node name and the default NSP segment size will be 
returned. This value must be an integer variable or constant. 
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* buf 

specifies the array/string containing the received data. In FORTRAN, the buffer 
must start on an even (byte) word boundary. On return from the call, the data is 
stored as follows: 

Length (in bytes/ 

characters) Content/Meaning 

6 Local node name in ASCII (left justified and filled with spaces if the 

name is less than 6 bytes/characters) 

2 Default NSP segment size 

Error/Completion Codes: 

1 The call completed successfully. 

-4 Data overrun. The network data was longer than the specified buffer. As much data as 
fits into the buffer is transferred to it; any remaining data is lost. 

-9 The task is not a network task; OPNNT did not execute successfully. 

-10 The network is not accessed on this LUN. 

-13 You are using an invalid buffer; the buffer specified to receive network data is outside the 
user task address space, or (for FORTRAN) it is not word aligned. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-1 1M/M-PLUS Executive Reference Manual. 
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GNDNT 



Get Network Data 

3.7.11 GNDNT - Get Network Data 

Use: 

Call GNDNT from either task to get data from that task's network data queue 
and store it in the specified mail buffer (see mailbuf). If the call completes 
successfully, the variable specified by the type argument will contain a code to 
indicate which of the following unsolicited message types has been stored: 

• Connect request {type code 1) 

• Interrupt message {type code 2) 

• User disconnect notice {type code 3) 

• User abort notice {type code 4) 

• Network abort notice {type code 5) 

Only one GNDNT request can be outstanding. If you issue a GNDNT while 
another GNDNT is outstanding, your request will complete with an error (-14). 

Formats: 

FORTRAN: CALL GNDNT [W] {[status], type,[mailsz], [mailbuf], 

[Itonly] , [immed] [, typmsk] ) 

COBOL: CALL "GNDNT [W]" USING [status],type,mailsz,mailbuf, 

[Itonly], [immed] [, typmsk] . 

BASIC: CALL GNDNT [W] BY REF {[status%{)],type%,mailsz%, 

mailbuf %, [Itonly %], 
[immed%][,typmsk%]) 
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Arguments: 

* status 

specifies an array/data item containing completion status information on return 
from GNDNT. In COBOL and BASIC, you cannot omit status, but you can 
specify for status if you do not want status information returned. See the 
discussion of square brackets in Section 3.6 for more information on omitting 
optional arguments. If specified, this optional 2-element integer array/data item 
will contain the following values when the call completes: 

First Status Word 

status%(0) (BASIC) or 

statusd) (FORTRAN, COBOL): 

Error/completion code (see list below). 

Second Status Word 

status%(l) (BASIC) or 

status(2) (FORTRAN, COBOL): 

Contents depends on error/completion code in first status word, as described in 
Status Table A. 

Status Table A 

If GNDNT completes with an error: 

Contents of First Status Word Contents of Second Status Word 



-40 

-n (other than -40) 

If GNDNT completes successfully and the 
Contents of First Status Word 

+n 

If GNDNT completes successfully and the 
Contents of First Status Word 

+n 



Directive error code 


Itonly flag is -1 (.TRUE.): 

Contents of Second Status Word 

Low-order byte contains the number of 
bytes/characters in the first network data item 
stored in the queue. 

Itonly flag is (.FALSE.): 

Contents of Second Status Word 

Content depends on data message type. Each 
message type is listed in Status Table B, fol- 
lowed by the contents of the second status word 
on return from GNDNT. 
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Status Table B 

Contents of Second Status Word 



Type 
Code 



Message 
Type 



Low-order Byte 



High-order Byte 



Connect 
request 



Interrupt 
message 



User 

disconnect 

User abort 

Network 
abort 



Number of bytes/char- 
acters in the connect 
block (the connect 
block data determines 
whether request will be 
accepted (ACCNT) or 
rejected (REJNT)) 

Number of bytes/char- 
acters in the message. 
If 0, no message was 
received. 



Access verification * and privilege code: 

1 = Requesting user is nonprivileged. 

2 = Requesting user is privileged. 
= Verification was not done ** 

-1 = Verification failed *** 



LUN over which the notice was received. 



Reason for network 
abort (see codes in Ap- 
pendix A). 



LUN over which the notice was received. 



* If access verification is enabled for the target node, it evaluates access control data in the 
connect request before it is allowed to pass to the target task's network data queue. For more 
information on access control, refer to the DECnet-RSX Network Management Concepts 
and Procedures manual. 

** Either the verification task was not installed on the target node, or it was set to OFF with 
the NCP SET EXECUTOR VERIFICATION command, or the proper access control file 
was not available or verification state for the object is off. 

*** Either the account is not in the system account file or the password does not match the one 
in the file. 

* type 

specifies an integer variable containing the data message type code on return from 
GNDNT. The code indicates the type of data message in the target task's mail 
buffer on return from GNDNT. Type codes and corresponding message types are 
listed in Status Table B, above. 
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mailsz 



specifies size of task's mail buffer in bytes/characters. In FORTRAN, this integer 
variable or constant can be omitted if you specify Itonly as .TRUE. In COBOL 
and BASIC, it can be set to if you specify Itonly as -1. Otherwise, mailsz must 
be a value greater than 0. 



specifies a 1- to n-element array/string containing the network data on return 
from GNDNT (see Table 3-2). In FORTRAN, this array must start on an even 
byte (word) boundary; it can be omitted if you specify Itonly as .TRUE. In 
COBOL and BASIC, it can be set to if you specify Itonly as -1. 



specifies dynamic assignment of mail buffer space. When you specify Itonly as 
.TRUE, (for FORTRAN) or as -1 (for COBOL and BASIC), the message type 
code of the first message in the network data queue is returned in the type 
variable, and the message length is stored in the low-order byte of the second 
status word; the message is not removed from the queue or placed in the mail 
buffer. 

If you specify the typmsk argument (see below), you must specify Itonly as in 
COBOL and BASIC; in FORTRAN, you must omit Itonly or specify it as 
.FALSE. In COBOL and BASIC, Itonly can be omitted only if all trailing argu- 
ments are omitted. For information on omitting arguments in COBOL and BA- 
SIC, refer to the discussion of square brackets [ ] in Section 3.6. 

immed 

specifies GNDNT action based on data in network data queue. 



mailbuf 



Itonly 



Value of immed 



Data in 

Network 

Queue? 



GNDNT Action 



_.TRUE. (FORTRAN) 
or - 1 (COBOL and BA- 
SIC) 



Yes 



GNDNT completes normally 



No 



GNDNT completes with error code 
-6 (no data in queue). 

GNDNT completes normally. 



FALSE (FOR- 
TRAN) or (COBOL 
and BASIC) or omitted 



Yes 



No 



GNDNT does not complete until there is 
data in the queue. 
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Note that immed cannot be omitted in COBOL or BASIC unless all trailing 
arguments are also omitted. For information on omitting arguments in COBOL 
and BASIC, refer to the discussion of square brackets [ ] in Section 3.6. 

typmsk 

specifies data type to be selected from network data queue. Normally, GNDNT 
returns items from the network data queue on a first-in, first-out basis. You can 
specify an integer variable or constant for typmsk to select the first item on the 
queue that matches the message type and/or LUN that you choose. 



Table 3-2: Connect Block Received in the Mail Buffer after GNDNT 



Length (in decimal 
bytes/characters) Contents 



2. Temporary logical link address 

(required by the network; do not modify) 

2. NSP segment size 

(used by NSP to send message data to source) 

DESTINATION DESCRIPTOR 

(20.-byte/character total) 

1. Destination descriptor format type 

(0 for BFMTO, or 1 for BFMT1) 

1. Destination object type 

(1-255. for BFMTO, or for BFMT1) 

Descriptor Field for Format 
18. Not used 

Descriptor Fields for Format 1 

2. Destination program name length 

(equal to or less than 16. bytes/characters) 

16. Destination program name 



(continued on next page) 
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Table 3-2 (cont.): Connect Block Received in the Mail Buffer after GNDNT 



Length (in decimal 
bytes/characters) Contents 

SOURCE DESCRIPTOR 

(26. -byte/character total) 

6. Source node name 

(name of node requesting the connection; ASCII, with trailing 
blanks) 

1. Source descriptor format type 

(must be either format or format 1) 

1. Source object type 

(object type of program requesting connection: 
1-255. for format 0, or for format 1) 

Descriptor Field for Format 

18. Not used 

Descriptor Fields for Format 1 

2. Source program name length 

(equal to or less than 16. bytes/characters) 

16. Source program name 

ACCESS CONTROL 

(46.-byte/character total) 

// no verification performed 

2. Source program user ID length 

(equal to or less than 16. bytes/characters) 

16. Source program user ID 

2. Source program password length 

(equal to or less than 8. bytes/characters) 

8. Source program password 

2. Account number length 

(equal to or less than 16. bytes/characters) 



(continued on next page) 
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Table 3-2 (cont.): Connect Block Received in the Mail Buffer after GNDNT 



Length (in decimal 
bytes/characters) Contents 

ACCESS CONTROL 

16. Account number 

// verification performed 
2. Default device name for destination program 

1. Default device unit number 

1. Not used 

2. Log-in UIC from account file 

(used for destination program) 

11. Default directory string 

(0 if no default string) 

29. Not used 

OPTIONAL DATA 

(18. -byte/character total) 

2. Length of optional user data 

(equal to or less than 16. bytes/characters; if no optional data) 

16. Optional user data sent by source program 

(0 to 16. bytes/characters) 
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Message Type (byte 0) 



Logical Unit Number (byte 1) 



1 Connect request 



(Selects the first LUN to request a connect.) 



2 Interrupt message 



or LUN 



3 User disconnect 



or LUN 



4 User abort 



or LUN 



5 Network abort 



or LUN 



Selects any message type 



LUN 



on the specified LUN 

For example, if you want to select from the network data queue the first interrupt 
message (type 2) on LUN 3, you would use a variable for the typmsk argument, 
declare it as an integer, and assign a value to it, as shown here: (3*256.) +2. 

If you specify in byte 1, the first message of the type specified in byte will be 
returned, regardless of the LUN. 



NOTE 



If you specify typmsk, you must also include mailsz and mailbuf, and 
you must specify Itonly as in COBOL and BASIC, and as .FALSE, 
in FORTRAN. If you use typmsk, you can omit Itonly in FORTRAN, 
but not in COBOL or BASIC. 
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Error/Completion Codes: 

1 The call completed successfully. 

2 The call completed successfully, but some returned optional data was lost. 

-4 Data overrun. The network data was longer than the mail buffer. As much data as will fit 
into the mail buffer is transferred to it; any remaining data is lost. 

-6 There is no data in the network data queue to return. 

-9 The task is not a network task; either OPNNT did not execute successfully, or CLSNT 
was issued with this GNDNT pending. 

-10 The network is not accessed on this LUN. 

-13 You are using an invalid buffer; the mail buffer is outside the user task address space, or 
(for FORTRAN) it is not word aligned. 

-14 A GNDNT is already pending. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-llM/M-PLUS Executive Reference Manual. 
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OPNNT 



Access the Network 



3.7.12 OPNNT - Access the Network 
Use: 

Call OPNNT to establish the task as an active network task and create the task's 
network data queue. You must call OPNNT before calling any other network 
subroutine. 

Formats: 

FORTRAN: CALL OPNNT[W] ([lun],[status],[mstat],[count][,lrp]) 

COBOL: CALL "OPNNT[W]" USING [lun], [status], [mstat], 

[count][,lrp]. 

BASIC: CALL OPNNT[W] BY REF ([lun%],[status%Q],[mstat%Q], 

[count%][,lrp%]) 

Arguments: 

lun 

specifies a logical unit number for the task's network data queue. This value must 
be an integer variable or constant. You can omit this argument if you have 
already assigned the LUN to NS: by using the GBLDEF option of .MBXLU at 
task build time (Section 1.2.2). However, when lun is omitted in COBOL or 
BASIC, all trailing arguments must also be omitted. For information on omitting 
arguments in COBOL and BASIC, refer to the discussion of square brackets [ ] in 
Section 3.6. 

* status 

specifies completion status information on return from OPNNT. See definition 
for your language in Section 3.7.1. 
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mstat 



specifies a 3-element integer array (or elementary numeric data item for COBOL) 
to contain current status information of the task's network data queue. When 
specified(+), the mstat array/data item is updated whenever data arrives or is 
retrieved by a GNDNT. This array/data item must not be used for other purposes 
while the task is active on the network. 

Values returned in this array/data item are: 

mstat(l) Number of items in network data queue 

mstat(2) Data type of first data item: 

1 - Connect request 

2 - Interrupt message 

3 - User disconnect 

4 - User abort 

5 - Network abort 

mstat(3) length of first data item 
count 

specifies the maximum number of simultaneously active connections the task will 
accept. When the number of active logical links equals the count value, the 
network rejects any incoming connect request. This integer variable or constant 
must not exceed 255 (decimal). A value of (which is also the default) sets no 
limit as long as network resources are available. 

To prevent access to your task, specify a count value of 1 so that GNDNT will 
reject all incoming connect requests. You can still establish outgoing links by 
using CONNT. 

Irp 

specifies the link recovery period - that is, the number of seconds that can elapse 
from the time of a physical link failure until the associated logical link is consid- 
ered irrecoverable. This integer variable or constant must be in the range of 
through 32767 (decimal). 

When specifying an Irp value, remember that your task will be locked in memory 
until the link recovery period has elapsed if the task has outstanding I/O when the 
link fails. This can cause serious delays for other system users who need to access 
the occupied area of memory. 
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Error/Completion Codes: 

1 The call completed successfully. 

-1 System resources needed for the network data queue are not available. 

-10 The network is being dismounted, or the user task has already accessed the network. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-11M/M-PLUS Executive Reference Manual. 
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RECNT 



Receive Data over a 
Logical Link 

3.7.13 RECNT - Receive Data over a Logical Link 

Use: 

Call RECNT from either task to receive data over an established logical link and 
store it in a specified buffer. 

Formats: 

FORTRAN: CALL RECNT[W] (lun,[status],insize,indata) 
COBOL: CALL "RECNT[W]" USING lun, [status], insize,indata. 
BASIC: CALL RECNT[W] BY REF {lun%,[status%{)),insize%,indata%) 
Arguments: 
lun 

specifies the logical unit number for the logical link over which data is to be 
received. It must be an integer variable or constant. If you initiated the connec- 
tion, enter the LUN you used in the CONNT call. If you accepted the connection, 
enter the LUN you used in the ACCNT call. 

* status 

specifies completion status information on return from RECNT. See definition for 
your language in Section 3.7.1 and note this addition: If a positive value or -4 
(data overrun) is returned in the first status word, the second status word con- 
tains the number of bytes/characters of data received. 

insize 

specifies the receive data buffer length in bytes/characters. This integer variable 
or constant can be a maximum of 8128 (decimal). 

* indata 

specifies the array/string containing the received message data. 
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Error/Completion Codes: 

1 The call completed successfully. 

-2 No logical link has been established on the specified LUN. 
-3 The logical link was disconnected during I/O operations. 

-4 Data overrun. More message data was transmitted than requested. As much data as will 
fit into the receive buffer is transferred to it; any remaining data is lost. 

-9 The task is not a network task; OPNNT did not execute successfully. 

-13 You are using an invalid buffer; either the indata array/string is outside the user task 
address space, or the buffer size (insize) exceeds 8128. bytes/characters. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-11M/M-PLUS Executive Reference Manual. 
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RE J NT 



Reject Logical Link 
Connect Request 

3.7.14 REJNT - Reject Logical Link Connect Request 

Use: 

Call REJNT from the target task to reject a logical link connect request. When 
you call REJNT, you can send 1- to 16. bytes/characters of user data to the 
requesting task (see the outsize,outmessage arguments). 

Formats: 

FORTRAN: CALL REJNT [W] ([status],mailbuf[,outsize,outmessage]) 

COBOL: CALL "REJNTfW]" USING [status], mailbuf, 

[outsize, outmessage] . 

BASIC: CALL REJNTfW] BY REF {[status%{)],mailbuf%, 

[outsize%,outmessage§]) 

Arguments: 

* status 

specifies completion status information on return from REJNT. See definition for 
your language in Section 3.7.1. 

mailbuf 

specifies the 1- to n-element array/string containing information necessary to 
reject the connect request. In FORTRAN, this array must start on an even byte 
(word) boundary. This array/string is the same one referred to in GNDNT (see 
Section 3.7.11). 

outsize, outmessage 

defines optional user data you want to send. See definition in Section 3.7.1. 
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Error/Completion Codes: 

1 The call completed successfully. 

-3 The task that requested the connection has aborted or has requested a disconnect before 
the connection could complete. 

-5 Either the temporary link address in the mail buffer is not valid, or the optional user data 
buffer exceeds 16. bytes/characters. 

-9 The task is not a network task; OPNNT did not execute successfully. 

-10 The network is not accessed on this LUN. 

-13 You are using an invalid buffer; the mailbuf or outmessage array/string is outside the user 
task address space, or (for FORTRAN) the mailbuf array is not word aligned. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-11M/M-PLUS Executive Reference Manual. 
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SNDNT 



Send Data over a 
Logical Link 

3.7.15 SNDNT - Send Data over a Logical Link 
Use: 

Call SNDNT from either task to send message data over the logical link. 
Formats: 

FORTRAN: CALL SNDNT[W] (lun,[status],outsize,outdata) 
COBOL: CALL "SNDNT[W]" USING lun,[status], outsize, outdata. 
BASIC: CALL SNDNT[W] BY REF (lun%,[status%()],outsize%,outdata$) 
Arguments: 
lun 

specifies the logical unit number for the logical link over which data is to be sent. 
It must be an integer variable or constant. If you initiated the connection, enter 
the LUN you used in the CONNT call. If you accepted the connection, enter the 
LUN you used in the ACCNT call. 

* status 

specifies completion status information on return from SNDNT. See definition for 
your language in Section 3.7.1 and note this addition: If a 1 is returned in the first 
status word, the second status word contains the number of bytes/characters of 
transmitted data. 

outsize 

specifies the length in bytes/characters of the data you want to send. This integer 
variable or constant can be a maximum of 8128 (decimal). 

outdata 

specifies a 1- to n-element array/string containing the message data you want to 
send. 
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Error/Completion Codes: 

1 The call completed successfully. 

-2 No logical link has been established on the specified LUN. 

-3 The logical link was disconnected during I/O operations. 

-9 The task is not a network task; OPNNT did not execute successfully. 

-13 You are using an invalid buffer; either the outdata array/string is outside the user task 
address space, or the buffer size {outsize) exceeds 8128. bytes/characters. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-1 1M/M-PLUS Executive Reference Manual. 
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WAITNT 



Suspend the Calling Task 

3.7.16 WAITNT - Suspend the Calling Task 
Use: 

Call WAITNT from any task to suspend that task's operation until a call speci- 
fied by one of the associated status blocks completes. 

Formats: 

FORTRAN: CALL WAITNT ([index], statusl,...,statusn) 
COBOL: CALL "WAITNT" USING [index],statusl,...,statusn. 
BASIC: CALL WAITNT BY REF ([index%],statusl%(),...,statusn%()) 
Arguments: 

* index 

specifies an integer variable containing the positional number of the status block 
associated with the call that has completed. 

In COBOL and BASIC, you cannot omit index, but you can specify for index if 
you do not want index information returned. See the discussion of square brackets 
in Section 3.6 for more information on omitting optional arguments. 

statusl,..., status n 

specifies one or more status blocks. WAITNT completes when any one of the calls 
associated with a status block in this list completes. 
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XMINT 



Send Interrupt Message 

3.7.17 XMINT - Send Interrupt Message 
Use: 

Call XMINT from either task to send an interrupt message over an established 
logical link. The message you send is placed on the target task's network data 
queue and must be retrieved with a GNDNT before you can issue another 
XMINT. 

Formats: 

FORTRAN: CALL XMINT[W] (lun t [status],intsize,intmsg) 
COBOL: CALL "XMINT[W]" USING lun,[status],intsize,intmsg. 
BASIC: CALL XMINT[W] BY REF (lun%,[status%()],intsize%,intmsg$) 
Arguments: 
lun 

specifies the logical unit number for the logical link over which the interrupt 
message is to be sent. It must be an integer variable or constant. If you initiated 
the connection, enter the LUN you used in the CONNT call. If you accepted the 
connection, enter the LUN you used in the ACCNT call. 

* status 

specifies completion status information on return from XMINT. See definition for 
your language in Section 3.7.1. 

intsize 

specifies the length in bytes/characters of the interrupt message you want to send. 
It must be an integer variable or constant. 

intmsg 

specifies a 1- to 16. -element array/string containing the interrupt message you 
want to send. 
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Error/Completion Codes: 

1 The call completed successfully. 

-2 No logical link has been established on the specified LUN. 

-3 The logical link was disconnected during I/O operations. 

-5 The interrupt message exceeds 16. bytes/characters. 

-9 The task is not a network task; OPNNT did not execute successfully. 

-11 An interrupt message was transmitted before a previous interrupt message had been 
received by the remote task. 

-13 You are using an invalid array/string; the intmsg array/string is outside the user task 
address space. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-11M/M-PLUS Executive Reference Manual. 
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3.7.18 FORTRAN Intertask Communication Programming Example 
(Transmit) 



The following two programs (Transmit and Receive) are examples of FORTRAN 
intertask communication. They are cooperating tasks. FTNTRN is a transmit task. 
FTNREC is a receiver task. FTNTRN accesses the network, connects to FTNREC, 
transmits inquiries to FTNREC, and receives responses from FTNREC. 

NOTE 

These programming examples are also included in your tape or disk 
kit. 



c 

C TO TASK BUILD USE THE FOLLOWING COMMAND STRING: 
C 

C FTNTRN , FTNTRN= FTNTRN ,[1,1] NETFOR/LB , F4 POTS /LB , RMSL I B/LB 
C / 

C UNITS=10 
C ACTFIL-4 

C EXTTSK-1000 (if RMS included) 

C // 

C 

INTEGER* 2 MLTYP , RECS I Z , SNDS I Z , OPNLUN , CONLUN , MESNUM , XMI TS , NDLEN , TSKLEN 
INTEGER* 2 IOST(2) ,MSTAT(3) 

BYTE ERRMES(2) , TSKNAM(6) ,CONBLK(72) ,NDNAM(6) , DEFNOD ( 6 ) , DEFTSK ( 6 ) 
BYTE SNDBUF ( 50 ) , RECBUF ( 10 ) 
LOGICAL*l STAT , IMMED 

DATA DEFNOD/'M' , 'A' , 'S' , 'T' , 'E' , 'RV 
DATA DEFTSK/'R' , 'E' , ' C , 'V , 'E' ,'R'/ 

C 

C INITIALIZE CONSTANTS 
C 

IMMED=.TRUE. 
OPNLUN- 1 
CONLUN=2 

XMITS=20 

SNDS I Z= 50 

RECS I Z= 10 



C 

C GET THE NODE AND TASK NAMES 
C 

4 TYPE 300 !* ASK FOR NODE-NAME 
READ(5,310) ( NDNAM ( NDLEN ) ,NDLEN= 1,6) !* GET THE NAME 

DO 5 NDLEN=6,1,-1 !* LOOP TO FIND LENGTH OF NAME 

IF ( NDNAM ( NDLEN ) .NE. ' ') GOTO 6 !* IF NOT A SPACE, GET TASK-NAME 

5 CONTINUE 

DO 50 1=1,6 

50 NDNAM ( I )=DEFNOD( I ) !* DEFAULT NODE NAME 'MASTER' 

NDLEN=6 !* LENGTH OF DEFAULT NAME 



(continued on next page) 



!* SET IMMED TO TRUE FOR GNDNTW 
!* NETWORK OPNNT LUN 
!* COUNT LUN FOR THE 
S* LOGICAL LINK 
!* THE NUMBER OF INQUIRIES 
! * TO BE SENT TO THE REMOTE NODE 
!* THE SIZE OF THE THE MESSAGES TO 
!* BE SENT TO THE REMOTE NODE 
!* THE SIZE OF THE MESSAGES TO 
!* BE RECEIVED 
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6 TYPE 320 !* ASK FOR THE TASK-NAME 
READ(5,310) ( TSKNAM ( TSKLEN ) , TSKLEN= 1,6) ! * GET I T 

DO 7 TSKLEN=6,1,-1 !* TSKLEN IS LENGH OF TASK-NAME 

IF ( TSKNAM ( TSKLEN ) .NE. ' ') GOTO 8 !* IF NOT SPACE, ACCESS NETWORK 

7 CONTINUE 

DO 60 1=1,6 

60 TSKNAM ( I ) =DEFTSK( I ) !* DEFAULT TASK NAME 'RECVER* 

TSKLEN=6 !* LENGTH OF DEFAULT NAME 

C 

C ACCESS NETWORK 
C 

8 CALL OPNNTW ( OPNLUN , I OST , MSTAT ) 

IF ( IOST(l) .NE.DGOTO 100 !* IF FAILURE JUST EXIT 

C 

C BUILD A FORMAT 2 CONNECT BLOCK 



C 
C 
C 
10 



15 

C 
C 
C 

C 
C 
C 



c 
c 
c 

20 



C 
C 
C 
30 



CALL BFMT 1 ( STAT , CONBLK , NDLEN , NDNAM , , TSKLEN , TSKNAM ) 

IF (STAT) GOTO 10 ! * IF SUCCESS GO ON 

TYPE 200 !* ELSE TYPE OUT A FAILURE 

!* NOTIFICATION 
GOTO 90 !* AND EXIT 

CONNECT TO THE TASK ON THE REMOTE NODE 



CALL CONNTW ( CONLUN , I OST , CONBLK ) 
IF (IOST(D.EQ.l)GOTO 15 !* 

TYPE 240,IOST !* 
GOTO 90 ! * 

! * 

TYPE 220 !* 

i * 



IF SUCCESS TELL HIM 
ELSE PRINT STATUS BLOCK 
DEACCESS THE NETWORK 
AND EXIT 

PRINT CONNECT CONFIRMATION 
NETWORK AND EXIT 



SEND AND RECEIVE MESSAGES TO AND FROM THE REMOTE NODE 

DO 40 MESNUM=1,XMITS 

FIRST GET ANY ERROR MESSAGES SENT FROM THE OTHER SIDE VIA 
INTERUPT MESSAGES 

IF (MSTAT(l) .EQ.0)GOTO 20 !* IF MSTAT(1)=0 NO MESSAGES 

!* ARE THERE 

CALL GNDNTW( IOST,MLTYP , 2 , ERRMES , , IMMED, 2 ) !* GET THE MESSAGE 
IF (IOST(l) .NE.DGOTO 20 !* IF WE COULDN'T GET THE MESSAGE 

!* JUST IGNORE IT 
TYPE 2 10, ERRMES (1) !* PRINT OUT THE MESSAGE 

SEND THE INQUIRY 

CALL SNDNTW ( CONLUN , I OST , SNDS I Z , SNDBUF ) 

IF (IOST(D.EQ.l)GOTO 30 !* IF SUCCESS CONTINUE 

TYPE 210,MESNUM !* OTHERWISE TYPE OUT AN 

!* ERROR MESSAGE 
GOTO 40 !* AND START A NEW MESSAGE 

RECEIVE THE RESPONSE FROM THE REMOTE NODE 

CALL RECNTW ( CONLUN , I OST , RECS I Z , RECBUF ) 
IF (IOST(I) .EQ.DGOTO 40 !*IF SUCCESS CONTINUE 

TYPE 210,MESNUM !* OTHERWISE TYPE OUT AN 

!* ERROR MESSAGE 



(continued on next page) 
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40 CONTINUE 
C 

C DISCONNECT THE LINK 
C 

TYPE 230 !* PRINT OUT DISCONNECT MESSAGE 

CALL DSCNTW ( CONLUN , I OST ) 

C 

C COME HERE TO DEACCESS THE NETWORK AND EXIT 
C 

90 CALL CLSNTW 

100 STOP 'END OF PROGRAM EXECUTION' 

C 

C FORMAT STATEMENTS 



200 


FORMAT 


C 


ERROR BUILDING CONNECT BLOCK') 




210 


FORMAT 


( ' 


ERROR ON INQUIRY ',13) 




220 


FORMAT 


( ' 


LINK ENABLED 1 ) 




230 


FORMAT 


(' 


LINK DISABLED' ) 




240 


FORMAT 


C 


CONNECT FAIL: IOST= ',13) 




300 


FORMAT 


C 


PLEASE ENTER NODE-NAME <MASTER>: 


',$) 


310 


FORMAT 


(6A1) 




320 


FORMAT 


(' 


PLEASE ENTER TASK-NAME <RECVER>: 


',$) 




END 
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3.7.19 FORTRAN Intertask Communication Programming Example 
(Receive) 

When FTNTRN completes sending inquiries, it disconnects the link, deaccesses the 
network, and exits. Any error found by FTNREC is transmitted back to FTNTRN as 
an interrupt message. FTNTRN then displays the interrupt message on the terminal. 



TO TASK BUILD USE THE FOLLOWING COMMAND STRING: 
FTNREC , FTNREC* FTNREC ,[1,1] NETFOR/LB , F4POTS/LB , RMSL IB/LB 



/ 

UNITS-10 
ACTFIL-4 
EXTTSK-1000 

// 



(if RMS included) 



INTEGER* 2 OPNLUN , MLTYP , I NDEX , ACCLUN , NUMBER , NUMMES 
INTEGER* 2 RECSIZ, SNDSIZ, INTSIZ 
INTEGER* 2 MSTAT ( 3 ) , IOST ( 2 ) , IOSTK2) , IOST2(2) 
BYTE RECBUF(50) ,SNDDAT(10) ,MLBX(98) , INTMES(2) 



10 
20 



INITIALIZE CONSTANTS 

OPNLUN" 1 
ACCLUN- 2 
RECSIZ* 50 
INTSIZ»2 
NUMMES-0 
SNDSIZ- 10 

ACCESS NETWORK 



!* NETWORK OPNNT LUN 

!* ACCNT LUN FOR THE LOGICAL LINK 

!* SIZE OF DATA BUFFER TO BE RECEIVED 

!* SIZE OF INTERRUPT DATA BUFFER TO SEND 

!* NUMBER OF MESSAGES RECEIVED 

!* NUMBER OF BYTES TO SEND BACK 



CALL OPNNTW ( OPNLUN , I OST , MSTAT ) 

IF ( IOST ( 1 ) . NE . 1 ) GOTO 100 

IF (MSTAT(l) .EQ.0)GOTO 40 

CALL GNDNT ( I OST1 , MLTYP , 98 , MLBX ) 

CALL WAITNT( INDEX, IOST1, IOST2) 

IF (lNDEX.EQ.2)GOTO 50 



NETWORK DATA HAS BEEN RECEIVED 

IF (IOSTI(I) .NE.DGOTO 40 

IF ( MLTYP. GE. 3) GOTO 40 

IF ( MLTYP. EQ. 2) GOTO 10 



IF FAILURE JUST EXIT 
IF NOTHING ON MAILBOX 



! * 
i * 

!* JUST CLOSE AND EXIT 
!* ISSUE A GET NETWORK DATA 
!* WAIT FOR A COMPLETION 
!* IF INDEX=2 A RECEIVE HAS 
!* BEEN COMPLETED 



!* IF GNDNT FAILED JUST 

!* CLOSE AND EXIT 

!* IF MULTYP>=3 THE LINK HAS 

!* BEEN BROKEN 

!* IF MLTYP= 2 WE'VE RECEIVED 
!* AN INTERRUPT MESSAGE, JUST 
!* ISSUE A NEW GNDNT 



WE'VE RECEIVED A CONNECT REQUEST - ISSUE AN ACCEPT 



CALL 
IF 



ACCNTW ( ACCLUN , I OST , MLBX ) 
(IOST(I) .NE.DGOTO 10 



!* IF FAILURE ISSUE A NEW 
!* GNDNT 



(continued on next page) 
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c 

C ISSUE A RECEIVE TO PICK UP DATA 
C 

3 CALL RECNT ( ACCLUN , I OST2 , RECS I Z , RECBUF ) 

GOTO 10 !* ISSUE A NEW GNDNT 

!* AND WAIT FOR A COMPLETION 

C 

C WE COME HERE UPON RECEIVING A DISCONNECT OR ABORT 
C 

40 CALL CLSNTW !* DEACCESS THE NETWORK 

GOTO 100 !* AND EXIT 

C 

C WE COME HERE IF WE RECEIVE AN INQUIRY 
C 

50 NUMMES=NUMMES+1 !* INCREMENT THE MESSAGE 

J* COUNT 

IF (IOST2Q) .EQ.DGOTO 60 t* IF IOST2(l)-l ALL'S O.K. 

C 

C IF THERE WAS AN ERROR SEND BACK AN INTERRUPT MESSAGE WITH 

C MESSAGE NUMBER 

C 

INTMES(1)=NUMMES !* SEND THE MESSAGE NUMBER 

CALL XM I NT ( ACCLUN , I OST , I NTS I Z , I NTMES ) 

GOTO 70 ! * GO ISSUE A NEW RECEIVE 

C 

C HERE THE USER CAN LOOK AT THE DATA RECEIVED IN RECBUF AND RESPOND 

C BY PLACING THE REQUESTED INFORMATION INTO SNDDAT 

C 

C 

C SEND BACK THE DATA AND ISSUE A NEW RECNT 
C 

6 CALL SNDNTW ( ACCLUN , I OST , SNDS I Z , SNDDAT ) 

70 CALL RECNT ( ACCLUN , I OST 2, RECS I Z, RECBUF) 

GOTO 20 !* WAIT FOR A COMPLETION 

C 

C EXIT PROGRAM 
C 

100 STOP 'END OF PROGRAM EXECUTION' !* HALT THE PROGRAM 

END !* AND EXIT 



3-54 



DECnet-RSX Programmer's Reference Manual 



3.7.20 COBOL Intertask Communication Programming Example 
(Transmit) 

The following two programs (Transmit and Receive) are examples of COBOL inter- 
task communication. They are cooperating tasks. COBTRN is a transmit task. CO- 
BREC is a receiver task. COBTRN accesses the network, connects to COBREC, 
transmits inquiries, and receives responses from COBREC. 

NOTE 

These programming examples are also included in your tape or disk 
kit. 



IDENTIFICATION DIVISION. 
PROGRAM- ID. COBTRN. 

********************************************** 



* * 

* THIS IS THE TRANSMIT PROGRAM OF THE DECNET COBOL * 

* INTERFACE COMMUNICATION EXAMPLE PROGRAMS. * 

* * 

* TO TASK BUILD USE THE FOLLOWING COMMAND STRING: * 

* * 



* COBTRN, COBTRN=COBTRN, [1, l]NETFOR/LB,C81LIB/LB,RMSLIB/LB 



* / * 

* UNITS=10 * 

* ACTFIL=4 * 

* EXTTSK-1000 (if RMS included) * 

* // * 

* * 

* * 



******************************************************************************* 



ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER . PDP- 1 1 . 
OBJECT-COMPUTER. PDP-11. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT DUMMY-FILE ASSIGN TO "COBTRN. DUM" . 



DATA DIVISION. 

FILE SECTION. 

FD DUMMY- FILE 

LABEL RECORD STANDARD. 
01 DUMMY-FILE-REC. 

02 FILLER PIC X(132). 



WORKING-STORAGE SECTION. 
01 MSGS. 



03 


MSG1. 














05 FILLER 


PIC 


X(32) 


VALUE " NETWORK 
"IOST(l) = 


OPEN 


FAILED, 




05 MSG1-STAT1 


PIC 


-99999. 










05 FILLER 


PIC 


X(ll) 


VALUE ■ IOST(2) 


_ n 






05 MSG 1- STAT 2 


PIC 


-99999. 








03 


MSG2. 














05 FILLER 


PIC 


X(25) 


VALUE ■ CONNECT 


FAIL, 


, IOST(l) 
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U5 MSG2-STAT1 


PIC 


-99999 




05 FILLER 


PIC 


X(ll) 




05 MSG 2 -STAT 2 


PIC 


-99999 


03 


MSG 3 . 








05 F I LLER 


PIC 


X(20) 




05 MSG3-ERR1 


PIC 


X( 2 ) . 


03 


MSG4 . 








05 FILLER 


PIC 


X(31) 




05 MSG4-NUM1 


PIC 


99. 


03 


MSG5. 








05 FILLER 


PIC 


X(34) 




05 MSG5-NUM1 


PIC 


99. 



1. ARRAYS. 



VALUE " IOST(2) « ". 

VALUE " ERROR ON INQUIRY # ". 

VALUE " ERROR ON INQUIRY DURI 
"NG SEND: ". 

VALUE " ERROR ON INQUIRY DURI 
"NG RECEIVE: " . 



01 



03 IOST. 

05 IOST AT 
03 MSTAT. 

05 MSTATS 
STORE-STUFF. 



OCCURS 2 TIMES PIC S9999 USAGE COMP. 
OCCURS 3 TIMES PIC S9999 USAGE COMP, 



03 


TEN 


PIC 


99 


COMP VALUE 


10. 


03 


OPNLUN 


PIC 


99 


COMP VALUE 


2. 


03 


RESULT-REC 


PIC 


X(80) . 






03 


IN-FILE 


PIC X(6). 






03 


NODNAM 


PIC X(6). 






03 


TSKNAM 


PIC 


X(9). 






03 


FILLER 


PIC 


X. 






03 


STAT 


PIC 


S999 


USAGE COMP. 




03 


CONBLK 


PIC X(72). 






03 


NLENG 


PIC 


9 


USAGE COMP. 




03 


TLENG 


PIC 


9 


USAGE COMP. 




03 


CONLUN 


PIC 


99 


COMP VALUE 


3. 


03 


XMITS 


PIC 


99 


COMP VALUE 


20. 


03 


MESNUM 


PIC 


99. 






03 


MLTYP 


PIC 


9. 






03 


FILLER 


PIC 


9. 






03 


MLBXSZ 


PIC 


99 


COMP VALUE 


2. 


03 


ERRMES 


PIC 


X(2). 






03 


DUMMY 


PIC 


X(2). 






03 


IMMED 


PIC 


S9 


COMP VALUE 


-1. 


03 


TYPMSK 


PIC 


SSS3SS. 






03 


FILLER 


PIC 


9. 






03 


SNDSIZ 


PIC 


99 


COMP VALUE 


50. 


03 


SNDBUF 


PIC 


X(50) . 






03 


RECSIZ 


PIC 


99 


COMP VALUE 


10. 


03 


RECBUF 


PIC 


X(10) . 







PROCEDURE DIVISION. 
A100-START. 

*********************************************** 

* * 

* INPUT NODE NAME AND RECEIVER TASK NAME FROM * 

* TERMINAL. * 



****************************************************************** 



DISPLAY "ENTER NODE-NAME <MASTER>". 

ACCEPT IN-FILE. 

MOVE IN-FILE TO NODNAM. 

DISPLAY "ENTER TASK-NAME <RECVER>" . 

ACCEPT IN-FILE. 

MOVE IN-FILE TO TSKNAM. 
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**************************************************** 

* * 

* ACCESS THE NETWORK. IF THE ACCESS IS UNSUCCESSFUL, * 

* PRINT AN ERROR MESSAGE AND EXIT. * 

* * 
***************************************************************** 

CALL "OPNNTW" USING 
OPNLUN 
IOST 
MSTAT 
TEN. 

IF IOSTAT U) = 1 

NEXT SENTENCE 

ELSE 

MOVE IOSTAT (1) TO MSG1-STAT1 
MOVE IOSTAT (2) TO MSG 1- STAT 2 
DISPLAY MSG1 
GO CO 00 -END. 

***************************************************************** 

* * 

* BUILD A FORMAT 1 CONNECT BLOCK. IF THE CALL DID * 

* NOT COMPLETE SUCCESSFULLY, PRINT AN ERROR MESSAGE * 

* AND DEACCESS THE NETWORK. * 

* * 
***************************************************************** 

MOVE 6 TO NLENG. 
MOVE 6 TO TLENG. 
CALL "BFMT1" USING 

STAT 

CONBLK 

NLENG 

NODNAM 

DUMMY 

TLENG 

TSKNAM 
IF STAT NOT = 

NEXT SENTENCE 

ELSE 

DISPLAY "ERROR BUILDING CONNECT BLOCK" 
GO B100-CLOSE. 

***************************************************************** 

* * 

* CONNECT TO THE TASK ON THE REMOTE NODE. IF THE * 

* CALL COMPLETES UNSUCESSFULLY, PRINT AN ERROR MESSAGE * 

* AND CLOSE THE NETWORK. OTHERWISE, PRINT "LINK * 

* ENABLED" MESSAGE. * 

* * 
***************************************************************** 

CALL "CONNTW" USING 

CONLUN 

IOST 

CONBLK. 
IF IOSTAT(l) = 1 

NEXT SENTENCE 

ELSE 

MOVE SPACES TO RESULT-REC 
MOVE IOSTAT(l) TO MSG 2- STAT 1 
MOVE IOSTAT(2) TO MSG 2 -STAT 2 
MOVE MSG 2 TO RESULT-REC 
DISPLAY RESULT-REC 
GO B100-CLOSE. 
DISPLAY "LINK ENABLED". 
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****************************************************** 

* * 

* SEND AND RECEIVE MESSAGES FROM THE REMOTE NODE. * 

* IF THERE IS SOMETHING ON THE NETWORK DATA QUEUE * 

* (MSTATS (1) > 0), GET THE MESSAGE. * 

* * 
***************************************************************** 



PERFORM LOOP VARYING MESNUM FROM 1 BY 1 UNTIL MESNUM = XMITS. 

LOOP. 

IF MSTATS(l) = 

NEXT SENTENCE 

ELSE 

CALL "GNDNTW" USING 

IOST 

MLTYP 

MLBXSZ 

ERRMES 

DUMMY 

IMMED 

TYPMSK 
IF IOSTAT(l) = 1 

NEXT SENTENCE 

ELSE 

MOVE SPACES TO RESULT- REC 
MOVE ERRMES TO MSG3-ERR1 
MOVE MSG3 TO RESULT-REC 
DISPLAY RESULT-REC. 



***************************************************************** 

* * 

* SEND A MESSAGE TO THE TASK ON THE REMOTE NODE. IF * 

* UNSUCCESSFUL, PRINT AN ERROR MESSAGE AND START THE * 

* NEXT TRANSMISSION. * 

* * 
***************************************************************** 



CALL "SNDNTW" USING 

CONLUN 

IOST 

SNDSIZ 

SNDBUF. 
IF lOSTAT(i) = I 

NEXT SENTENCE 

ELSE 

MOVE SPACES TO RESULT-REC 
MOVE MESNUM TO MSG4-NUM1 
MOVE MSG4 TO RESULT-REC 
DISPLAY RESULT-REC 
GO LOOP. 



***************************************************************** 

* * 

* RECEIVE A MESSAGE FROM THE REMOTE NODE. IF * 

* UNSUCCESSFUL, PRINT AN ERROR MESSAGE AND START * 

* THE NEXT TRANSMISSION. IF SUCCESSFUL, SIMPLY * 

* START THE NEXT TRANSMISSION. * 

* * 
***************************************************************** 
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CALL "RECNTW" USING 

CONLUN 

IOST 

RECSIZ 

RECBUF . 
IF IOSTAT(l) = 1 

NEXT SENTENCE 

ELSE 

MOVE SPACES TO RESULT-REC 
MOVE MESNUM TO MSG5-NUM1 
MOVE MSG 5 TO RESULT-REC 
DISPLAY RESULT-REC. 

************************************************ 

* * 

* DEACESS THE NETWORK. * 

* * 
***************************************************************** 

B000-ENDLOOP. 

DISPLAY "LINK DISABLED". 
CALL "DSCNTW" USING 
CONLUN 
IOST. 

***************************************************************** 

* * 

* CLOSE THE NETWORK AND EXIT. * 

* * 
***************************************************************** 

Bl 00 -CLOSE. 

CALL "CLSNTW". 

DISPLAY "END OF EXECUTION". 
CO 00 -END. 

STOP RUN. 
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3.7.21 COBOL Intertask Communication Programming Example 
(Receive) 

When COBTRN completes sending inquiries, it disconnects the link, deaccesses the 
network, and exits. Any error found by COBREC is transmitted to COBTRN as an 
interrupt message. COBTRN then displays the interrupt message on the terminal. 

IDENTIFICATION DIVISION. 
PROGRAM- ID. COBREC. 

*************************************************** 



* * 

* THIS IS THE RECEIVE PROGRAM OF THE DECNET COBOL * 

* INTERFACE COMMUNICATION EXAMPLE PROGRAMS. * 

* * 

* TO TASK BUILD USE THE FOLLOWING COMMAND STRING: * 

* * 

* COBREC , COBREC=COBREC ,[1,1] NETFOR/LB , C8 1 L I B/LB , RMSL I B/LB * 

* / * 

* UNITS=10 * 

* ACTFIL=4 * 

* EXTTSK=1000 (if RMS included) * 

* // * 

* * 

* * 



******************************************************************************* 

ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER . PDP- 1 1 . 
OBJECT-COMPUTER. PDP-11. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT DUMMY-FILE ASSIGN TO "COBREC. DUM" . 

DATA DIVISION. 

FILE SECTION. 

FD DUMMY- FILE 

LABEL RECORD STANDARD. 
01 DUMMY-FILE-REC. 

02 FILLER PIC X(132) . 

WORKING-STORAGE SECTION. 
01 ARRAYS. 
03 IOST. 

05 IOSTAT OCCURS 2 TIMES PIC S9999 USAGE COMP. 
03 MSTAT. 

05 MSTATS OCCURS 3 TIMES PIC S9999 USAGE COMP. 
03 IOST1. 

05 IOSTAT1 OCCURS 2 TIMES PIC S9999 USAGE COMP. 
03 IOST2. 

05 IOSTAT 2 OCCURS 2 TIMES PIC S9999 USAGE COMP. 
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01 STORE-STUFF. 



03 


OPNLUN 


PIC 


99 


COMP VALUE 


2. 


03 


MLTYP 


PIC 


9 


USAGE COMP. 




03 


MLSIZ 


PIC 


99 


COMP VALUE 


98 


03 


MLBOX 


PIC 


X(98) . 






03 


INDX 


PIC 


99 


USAGE COMP. 




03 


ACCLUN 


PIC 


99 


COMP VALUE 


3. 


03 


RECSIZ 


PIC 


99 


COMP VALUE 


50 


03 


RECBUF 


PIC 


X(50) . 






03 


NUMMES 


PIC 


99 


COMP VALUE 


0. 


03 


INTSIZ 


PIC 


9 


COMP VALUE 


6. 


03 


INTMES 


PIC 


X(6). 






03 


SNDSIZ 


PIC 


99 


COMP VALUE 


10 


03 


SNDDAT 


PIC 


X(10). 







PROCEDURE DIVISION. 

************************************************* 

* * 

* ACCESS THE NETWORK. IF THE CALL COMPLETES * 

* UNSUCCESSFULLY, EXIT. * 

* * 
***************************************************************** 

Al 00 -START. 

CALL "OPNNTW" USING 
OPNLUN 
IOST 
MSTAT. 
IF IOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

GO G100-END. 
IF MSTATS (1) = GO C100-CLOSNET. 

***************************************************************** 

* * 

* CHECK TO SEE IF THERE IS ANYTHING ON THE TASK'S * 

* DATA QUEUE. * 

* * 
***************************************************************** 

B100-NETDAT. 

CALL "GNDNT" USING 
IOST1 
MLTYP 
MLSIZ 
MLBOX. 

***************************************************************** 

* * 

* WAIT FOR COMPLETION OF A GNDNT OR RECNT CALL. IF A * 

* RECNT CALL COMPLETES (INDEX = 2), PROCESS A RECEIVE. * 

* IF A GNDNT CALL COMPLETES UNSUCCESSFULLY, CLOSE THE * 

* NETWORK AND EXIT. IF THE TYPE OF DATA MESSAGE IN * 

* THE MAILBOX IS NOT A CONNECT REQUEST OR AN INTERRUPT * 

* MESSAGE, CLOSE THE NETWORK AND EXIT. IF AN INTERRUPT * 

* MESSAGE IS IN THE MAILBOX (MLTYP =2), SIMPLY ISSUE * 

* A NEW GNDNT. * 

* * 
***************************************************************** 



(continued on next page) 



Programming Facilities for FORTRAN, COBOL, and BASIC-PLUS-2 



3-61 



Bl 10 -WAIT. 

CALL "WAITNT" USING 
INDX 
IOST1 
IOST2. 

IF INDX = 2 GO D100-INQREC. 

IF IOSTAT1 (1) NOT = 1 GO C100-CLOSNET. 

IF MLTYP NOT < 3 GO C100-CLOSNET . 

IF MLTYP = 2 GO B100-NETDAT. 

*************************************************** 

* * 

* A CONNECT REQUEST IS IN THE MAILBOX. ACCEPT THE * 

* REQUEST TO ESTABLISH A LOGICAL LINK. IF THE CALL * 

* COMPLETES UNSUCCESSFULLY, ISSUE A NEW GNDNT. * 

* * 

***************************************************************** 

CALL "ACCNTW" USING 
ACCLUN 
IOST 
MLBOX . 

IF IOSTAT (1) NOT = 1 GO B100-NETDAT. 

***************************************************************** 

* * 

* PICK UP THE DATA FROM THE TRANSMITTING TASK. ISSUE * 

* A NEW GNDNT AND WAIT FOR COMPLETION. * 

* * 
***************************************************************** 

CALL "RECNT" USING 

ACCLUN 

IOST2 

RECSIZ 

RECBUF. 
GO B100-NETDAT. 

***************************************************************** 

* * 

* A DISCONNECT OR ABORT WAS RECEIVED. DEACCESS THE * 

* NETWORK AND EXIT. * 

* * 
***************************************************************** 

C100-CLOSNET. 

CALL "CLSNTW". 
GO G100-END. 

***************************************************************** 

* * 

* AN INQUIRY WAS RECEIVED. INCREMENT THE MESSAGE * 

* COUNT. IF THE CALL COMPLETED UNSUCCESSFULLY, SEND * 

* AN INTERRUPT MESSAGE CONTAINING THE MESSAGE NUMBER * 

* IN WHICH THE ERROR OCCURRED. * 

* * 
***************************************************************** 
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D100-INQREC. 

ADD 1 TO NUMMES. 

IF IOSTAT2 (1) = 1 GO E100-SEND. 
MOVE NUMMES TO INTMES. 
CALL "XMINT" USING 

ACCLUN 

IOST 

INTSIZ 

INTMES. 
GO F100-REC. 

********************************** 

* * 

* SEND DATA TO THE TASK. * 

* * 
***************************************************************** 

E100-SEND. 

CALL "SNDNTW" USING 

ACCLUN 
IOST 
SNDSIZ 
SNDDAT . 

***************************************************************** 

* * 

* ISSUE A NEW RECNT AND WAIT FOR COMPLETION. * 

* t * 
***************************************************************** 

F100-REC. 

CALL "RECNT" USING 
ACCLUN 
IOST2 
RECSIZ 
RECBUF. 
GO B110-WAIT. 
G100-END. 

DISPLAY "COBREC — END OF EXECUTION". 
STOP RUN. 
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3.7.22 BASIC-PLUS-2 Intertask Communication Programming Example 
(Transmit) 

The following two programs (Transmit and Receive) are examples of BASIC-PLUS-2 
intertask communication. They are cooperating tasks. BASTRN is a transmit task. 
BASREC is a receiver task. BASTRN accesses the network, connects to BASREC, 
transmits inquiries to BASREC, and receives responses from BASREC. 

NOTE 

These programming examples are also included in your tape or disk 
kit. 



10 !!! To task build you must edit the task build command !!! & 

!!! file and the ODL file created by the build. !!! & 

! ! ! >Add the line ! ! ! & 

! ! ! ! ! ! & 

! ! ! ACTFIL=4 ! ! ! & 

!!! to the task build command file. !!! & 

! ! ! ! ! ! & 

! ! ! >Append ! ! ! & 

! ! ! ! ! ! & 

! • ! -NETLIB ! ! ! & 

!!! to the USER: line of the ODL file. ! ! ! & 

! ! ! ! ! ! & 

1 ! ! >Add the line I ! ! & 

! ! ! ! ! ! & 

! ! ! NETLIB : . FCTR LB : [ 1 , 1 ]NETFOR/LB ! ! ! & 

! ! ! to the ODL file. ! ! ! & 

! • ! DEFINE ARRAY CONSTANTS ! ! ! & 

DIM I0ST%(1%) ,MSTAT%(2%) ! DEFINE ARRAY ELEMENTS & 

\ ERRMES$=STRING$(2%,0%) ! DEFINE MAX STRING LENGTH & 

\ CONBLK$=STRING$(72%,0%) ! STRING$ ( LENGTH, ASCI I VALUE) & 

\ RECBUF$=STRING$(10%,0%) ! & 
\ SNDBUF$=STRING$(50%,0%) ! 

20 INPUT "NODE-NAME <MASTER>" ;NDNAM$ \ IF NDNAM$="" THEN & 

NDNAM$= "MASTER" ELSE IF LEN(NDNAM$ ) >6% THEN & 

PRINT "NODE-NAME TOO LONG, PLEASE RE-ENTER" & 
\ PRINT \ GOTO 20 

30 INPUT "RECEIVE TASK-NAME <RECVER>" ; TSKNAM? \ IF TSKNAM$="" & 

THEN TSKNAM$ = " RECVER " ELSE IF LEN(TSKNAM$ ) >6% THEN & 

PRINT "TASK-NAME TOO LONG, PLEASE RE-ENTER" & 
\ PRINT \ GOTO 30 
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40 


! ! ! DEFINE CONSTANTS ! ! ! 


& 




IMMED%= 


-1% !SET IMMED TO TRUE FOR GNDNTW 


S. 


\ 


OPNLUN% 


=1% [NETWORK OPNNT LUN 


S. 


\ 


CONLUN% 


= 2% [CONNT LUN FOR THE LOGICAL LINK 


& 


\ 


XMITS%= 


20% ! THE NUMBER OF INQUIRIES 


St 






!TO BE SENT TO THE REMOTE NODE 


& 


\ 


SNDSIZ% 


=50% ! THE SIZE OF THE MESSAGES TO 


& 






! BE SENT TO THE REMOTE NODE 


5, 


\ 


RECSIZ% 


=10% ! THE SIZE OF THE MESSAGES TO 


& 






! BE RECEIVED 


& 


\ 


NDNAM . LEN% = LEN ( NDNAM$ ) [LENGTH OF THE NODE-NAME 


& 


\ 


TSKNAM. 


LEN% = LEN ( TSKNAM$ ) ! LENGTH OF THE TASK-NAME 




50 


! ! ! ACCESS THE NETWORK ! ! ! 


& 




CALL 


OPNNTW BY REF ( OPNLUN% , I OST% ( ) , MSTAT% ( ) ) 


& 


\ 


IF 


IOST%(0%)=1% THEN 60 ! IF SUCCESSFUL, BUILD THE 


r 
oc 






[CONNECT BLOCK 


& 




ELSE 


PRINT "NETWORK OPEN FAILED, IOST=" ; IOST% ( 0% ) ; IOST% ( 1% ) 


& 


\ 


GOTO 


160 [OPEN FAILED. PRINT THE STATUS 


St 






[BLOCK AND EXIT 




60 


! ! ! BUILD A FORMAT 1 CONNECT BLOCK ! ! ! 


St 




CALL 


3FMT1 BY REF ( STAT% , CONBLK$ , NDNAM. LEN% , NDNAM$ 


i 






, DUMMY % , TSKNAM. LEN% , TSKNAM$ ) 


i 


\ 


IF 


STAT% THEN 70 ELSE [IF SUCCESS GO ON 


& 




PRINT 


"ERROR BUILDING CONNECT BLOCK" 


St 






•ELSE TYPE OUT AN ERROR MESSAGE 


St 


\ 


GOTO 


150 [AND EXIT 




70 


! ! ! CONNECT TO THE TASK ON THE REMOTE NODE ! ! ! 


St 




CALL 


CONNTW BY REF(CONLUN%, IOST%( ) ,CONBLK$) 


& 


\ 


IF 


IOST%(0%)=1% THEN 80 ! IF SUCCESS TELL HIM 


& 




ELSE 


PRINT "CONNECT FAIL: I OST=»" ; IOST% ( 0% );","; IOST% ( 1% ) 


St 






[ELSE PRINT STATUS BLOCK 


St 


\ 


GOTO 


150 [ELSE PRINT STATUS BLOCK AND EXIT 




PRINT 


"LINK ENABLED" [PRINT CONNECT COMF I RMAT I ON 


& 






[TO NETWORK 




90 


! ! ! SEND AND RECEIVE MESSAGES TO AND FROM THE REMOTE NODE ! ! ! 


St 




FOR 


MESNUM%=1% TO XMITS% 




100 




! ! ! FIRST GET ANY ERROR MESSAGES SENT FROM THE OTHER ! ! ! & 






! ! ! SIDE VIA INTERUPT MESSAGES ! ! ! 


s> 






IF MSTAT%(0%)=0% THEN 110 !IF MSTAT% ( 0% ) =0% NO MESSAGES 


St 






! ARE THERE 


St 






ELSE CALL GNDNTW BY REF( IOST%( ) ,MLTYP%, 2%,ERRMES$ 


St 






, DUMMY% , IMMED% , 2% ) 'GET THE MESSAGE 


St 


\ 




IF IOST%(0%)<>1% THEN 110 !IF WE COULDN'T GET MESSAGE 


St 






[JUST IGNORE IT 


St 






ELSE PRINT "ERROR ON INQUIRY #" ; ASCI I ( LEFT( ERRMES$ , 1% ) ) 








[PRINT OUT THE MESSAGE 




110 




! ! ! SEND THE INQUIRY ! ! ! 


& 






CALL SNDNTW BY REF ( CONLUN% , IOST% ( ) , SNDS I Z% , SNDBUF$ ) 


St 


\ 




IF IOST%(0%)=1% THEN 120 [IF SUCCESS CONTINUE 


St 






ELSE PRINT "ERROR ON INQUIRY DURING SEND: ";MESNUM% 


St 






[OTHERWISE TYPE OUT AN ERROR 


St 


\ 




GOTO 130 [MESSAGE AND START A NEW MESSAGE 
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120 ! ! ! RECEIVE THE RESPONSE FROM THE REMOTE NODE ! ! 1 & 

CALL RECNTW BY REF(CONLUN% , IOST% ( ) , RECSIZ% , RECBUF$ ) & 

\ IF IOST%(0%)=1% THEN 130! IF SUCCESS CONTINUE & 

ELSE PRINT "ERROR ON INQUIRY DURING RECEIVE: ";MESNUM% & 

! OTHERWISE TYPE OUT AN & 
! ERROR MESSAGE 

130 NEXT MESNUM% ! END OF LOOP 

140 ! ! ! DISCONNECT THE LINK ! ! ! & 

PRINT "LINK DISABLED" ! PRINT OUT DISCONNECT MESSAGE & 

\ CALL DSCNTW BY REF(CONLUN% , IOST% ( ) ) 

150 ! ! ! COME HERE TO DE ACCESS THE NETWORK AND EXIT ! ! ! & 

CALL CLSNTW 

160 PRINT "END OF EXECUTION" & 

\ END 
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3.7.23 BASIC-PLUS-2 Intertask Communication Programming Example 
(Receive) 

When BASTRN completes sending inquiries, it disconnects the link, deaccesses the 
network, and exits. Any error found by BASREC is transmitted to BASTRN as an 
interrupt message. BASTRN then displays the interrupt message on the terminal. 



To task build you must edit the task build command 
file and the ODL file created by the build. 

>Add the line 

ACTFIL=4 
to the task build command file. 

> Append 

' -NETLIB 

to the USER: line of the ODL file. 
>Add the line 



NETLIB: . FCTR LB : [ 1 , 1 ] NETFOR/LB 
to the ODL file. 



\ 
\ 
\ 
\ 

20 

\ 
\ 



! ! ! INITIALIZE CONSTANTS ! ! ! 
DIM MSTAT%(2%) ,I0ST%(1%) , I0ST1%(1%) ,I0ST2%(1%) 
INTMES$=STRING$ ( 2% , 0% ) 
MLBX$=STRI NG $ ( 98% , 0% ) 



RECBUF$=STRING$ ( 50% , 0% ) 
SNDDAT$=STRING$ ( 10% , 0% ) 

! ! ! MORE CONSTANTS ! ! ! 
OPNLUN%=l% 
ACCLUN%=2% 
RECSIZ%=50% 

INTSIZ%=2% 

NUMMES%=0% 

INDEX=0% 

SNDSIZ%=10% 



DEFINE MAX LENGTH OF STRINGS 
STRING$( LENGTH, ASCI I VALUE) 



! NETWORK OPNNT LUN 

! ACCNT LUN FOR THE LOGICAL LINK 

!SIZE OF DATA BUFFER TO BE 

•RECEIVED 

SSIZE OF INTERRUPT DATA BUFFER 
!TO SEND 

! NUMBER OF MESSAGES RECEIVED 

! RECEIVE COMPLETION FLAG 

! NUMBER OF BYTES TO SEND BACK 



30 ! ! ! ACCESS NETWORK ! ! ! 

CALL OPNNTW BY REF ( OPNLUN% , I OST% ( ) , MSTAT% ( ) ) 
\ IF IOST%(0%)<>1% THEN 140 !IF FAILURE JUST EXIT 

ELSE IF MSTAT%(0%)=0% THEN 90! IF NOTHING ON MAILBOX 

!JUST CLOSE AND EXIT 



40 



CALL 



GNDNT BY REF ( IOSTl% ( ) , MLTYP% , 98% , MLBX$ ) 

! ISSUE A GET NETWORK DATA 



50 CALL WAITNT BY REF ( INDEX% , IOSTl% ( ) , IOST2% ( ) ) & 

!WAIT FOR A COMPLETION & 

\ IF INDEX%=2% THEN 100 ! IF INDEX%=2% THEN A RECEIVE & 

•HAS BEEN COMPLETED 



(continued on next page) 
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60 ! ! ! NETWORK DATA HAS BEEN RECEIVED ! I ! & 

IF IOST1%(0%)<>1% THEN 90 ! IF GNDNT FAILED JUST & 

! CLOSE AND EXIT & 

ELSE IF MLTYP%>=3% THEN 90 ! IF MLTYP%>=3% THEN LINK HAS & 

! BEEN BROKEN & 

ELSE IF MLTYP%=2% THEN 40 ! IF MLTYP%=2% WE'VE RECEIVED & 

! AN INTERRUPT MESSAGE, JUST & 

! ISSUE A GNDNT 

7 !!! WE'VE RECEIVED A CONNECT REQUEST - ISSUE AN ACCEPT !«! 4 

CALL ACCNTW BY REF ( ACCLUN% , IOST% ( ) , MLBX$ ) & 
\ IF IOST%(0%)<>1% THEN 40 ! IF FAILURE ISSUE A NEW GNDNT 

80 ! ! ! ISSUE A RECEIVE TO PICK UP DATA ! 1 ! & 

CALL RECNT BY REF( ACCLUN% , IOST2%( ) , RECSIZ% ,RECBUF$ ) & 

\ GOTO 40 'ISSUE A NEW GNDNT AND & 

!WAIT FOR THE COMPLETION 

90 ! ! ! WE COME HERE UPON RECEIVING A DISCONNECT OR ABORT ! ! ! & 

CALL CLSNTW 1DEACCESS THE NETWORK & 
\ GOTO 140 ! AND EXIT 

100 ! ! ! WE COME HERE IF WE RECEIVE AN INQUIRY ! ! ! & 

NUMMES%=NUMMES%+1% ! INCREMENT THE MESSAGE COUNT & 
\ IF IOST2%(0%)=1% THEN 120 !IF IOST2%(0%)=1 ALL'S O.K. 

110 ! ! ! IF THERE WAS AN ERROR, SEND BACK AN INTERRUPT MESSAGE ! ! ! & 

1 ! 1 WITH MESSAGE NUMBER ! ! ! & 

INTMES$=CHR$(NUMMES%)+CHR$(0%) ! SEND THE MESSAGE NUMBER & 

\ CALL XMINT BY REF( ACCLUN% , IOST%( ) , INTSIZ% , INTMESS ) & 

\ GOTO 130 !GO ISSUE A NEW RECEIVE S. 

120 ! ! ! HERE THE USER CAN LOOK AT THE DATA RECEIVED IN RECBUF$ ! ! ! & 

! ! ! AND RESPOND BY REPLACING THE REQUESTED INFORMATION ! ! • & 

! ! ! INTO SNDDAT$ ! ! ! & 

! ! ! SEND BACK THE DATA AND ISSUE A RECNT 11! & 
CALL SNDNTW BY REF ( ACCLUN% , I OST% ( ) , SNDS I Z% , SNDDAT$ ) 

130 CALL RECNT BY REF( ACCLUN% , IOST2% ( ) ,RECSIZ% , RECBUF$ ) & 
\ GOTO 50 1WAIT FOR A COMPLETION 

140 ! ! ! EXIT PROGRAM ! ! 1 S. 

PRINT "END OF PROGRAM EXECUTION" & 
\ END 
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3.8 Remote File Access 



This section contains descriptions and usage guidelines specific to the remote file 
access calls listed alphabetically in Table 3-3. 



Table 3-3: Remote File Access Call Summary 



Call 


Function 


ACONFW 


To set record and file access options 


ATTNFW 


To set extended attributes 


CLSNFW 


To close a file 


DELNFW 


To delete a file 


EXENFW 


To execute a file 


GETNFW 


To read a single record 


OPANFW 


To open and append a sequential file 


OPMNFW 


To open and modify a sequential file 


OPRNFW 


To open and read a sequential file 


OPUNFW 


To open and update a sequential file 


OPWNFW 


To create, open, and write a sequential file 


PRGNFW 


To discard an open file 


PUTNFW 


To write a record to a file 


RENNFW 


To rename a file 


SPLNFW 


To open, write, and print a file 


SUBNFW 


To open, write, and execute a file 



These calls are implemented by subroutines. The network open call, OPNNT[W], and 
the network close call, CLSNTfW], are also used in remote file access operations. You 
must always issue OPNNT[W] first because OPNNTfW] allows your task to access 
the network. Issue CLSNT[W] last to close your task's access to the network. 
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3.8.1 Opening Files 

The following nine subroutines open files: 

ACONFW Specifies record and file access options before performing a specific file 
operation. 

ATTNFW Specifies extended attributes before performing OPWNFW, SPLNFW, 
SUBNFW, OPRNFW, OPANFW, and RENNFW calls. 

OPRNFW Opens an existing file for reading, beginning with the first record. 

OPANFW Opens an existing file and appends records to the end of the file. 

OPMNFW Opens an existing file for record modification. 

OPUNFW Opens an existing file for record update. 

OPWNFW Creates and opens a file, then writes records to it, beginning with the 
first record position. 

SPLNFW Performs the same function as OPWNFW and then prints the file. 

SUBNFW Performs the same function as OPWNFW and then executes the file. 

Each open subroutine creates a DECnet logical link to the node where the file resides 
and then creates and opens the file. You must use the same LUN to open, write, and 
close the file. This LUN must be one not in use. 

You must issue an ATTNFW or ACONFW call immediately before 
OPRNFW, OPANFW, and RENNFW calls to specify additional attributes to be re- 
turned after the open operation completes. 

3.8.2 Performing File Operations 

The following subroutines perform file operations: 
EXENFW Executes a remote file 
DELNFW Deletes a remote file 
RENNFW Renames a remote file 

3.8.3 Performing Record Operations 

The following subroutines perform record operations: 
GETNFW Reads a record from a remote file 
PUTNFW Writes a record to a remote file 
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3.8.4 Closing Files and Completing Calls 

When you complete a file access operation, use CLSNFW to close the file. If you want 
to clean up errors before closing the file, use PRGNFW for your close operation. Both 
CLSNFW and PRGNFW disconnect the logical link and free the logical unit number 
for use. If you do not perform a clost operation before attempting a CLSNT[W] to 
deaccess the network, or if a network abort occurs while the file is open, the network 
will close the file. However, all data may not have been transferred successfully. 

Remote file access calls are synchronous and do not return to the user until an 
operation completes. 

3.8.5 Setting Task Build Parameters 

DECnet-RSX uses network file access routines (NFARs) as the interface at the local 
node to access remote files for user applications. At task build time you can override 
defaults to tailor these NFARs for a particular application. Task build parameters 
you can set and their defaults are: 

• Event flags .TREF(default 17) and .RCEF(default 18) 

• Buffering level (default 2) 

• Maximum record size (default 256. bytes) 

• Buffer space allocation (no default) 

3.8.5.1 Setting Event Flags — The network file access routines (NFARs) require 
the exclusive use of two event flags. By default, the event flags used are 17(.TREF) 
and 18(.RCEF). To override these defaults, issue the following commands in the task 
builder command file: 

GBLDEF=.TREF:i>a/i/e 
GBLDEF=.RCEF:i;a/ue 

The value variable specifies an event flag and must be in the form of an octal integer 
from 1 to 200 (octal). Event flags 33. through 64. are global flags. 

3.8.5.2 Setting Buffering Level — The NFARs can be configured for multibuffering 
to improve throughput. However, this requires more internal buffering space. The 
default buffering level is 2. To override this default, issue the following command in 
the task builder command file: 

GBLDEF=$NFRS Z : buffering- level 

The buffering-level variable specifies an integer from 1 to 4. If the remote system is 
RSX or IAS, you can ask the system manager for the buffering level used for that 
system and use the same one. 
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3.8.5.3 Setting Maximum Record Size — The internal buffers used by the NFARs 
must be large enough to hold the largest data record in the remote file. The default 
maximum record size is 256 bytes. To override this default, include the following 
command in the task builder command file: 

GBLDEF=$NFRSZ:recorG?-s*'ze 

The record-size variable specifies an octal value. If the remote system is RSX or IAS, 
use the same record size used by the remote system. 

If you intend to transfer an ASCII file, add an extra 2 bytes when calculating the 
maximum record size. The extra 2 bytes are required for the carriage return and line 
feed characters that are appended to each ASCII record. If you intend to transfer 
sequenced variable length records, add an extra 2 bytes for the sequence number 
included with each record. If you intend to transfer an ASCII file with sequenced 
variable length records, add an extra 4 bytes. 

3.8.5.4 Setting Buffer Space Allocation — The NFARs allocate buffer space from 
the file storage region used by the File Control System (FCS-11). This space is 
allocated in the P-section $$FSR1. Note that the module NFAFSR from the NET- 
FOR object library must be included in your task. Be sure to enter the following line 
in the task build command as an input file: 

C 1 >1 ]NETFOR/LB:NFAFSR 

Use the following formula to calculate the amount of buffer space required to perform 
remote file access: 

(($NFRSZ+14.)*($NFNMB+l))+64.)*(max-rem-/i7es)+(512.*<max-/oc-/^es>) 
where 

max-rem-files is the maximum number of remote files that can be opened simulta- 
neously. 

max-loc-files is the maximum number of local files that can be opened simultane- 
ously. 

Note that the amount of space (512.) needed for local files will vary according to the 
language you are using. 

At task build time, extend the file storage region by the amount of space calculated by 
this formula by including the following command in the task builder command file 
(the value given must be in octal bytes): 

EXTSCT=$$FSR1 : value 
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3.8.5.5 Using the Task Build Procedure — It is necessary for a task to link to 
NETFOR.OLB in order to use the DECnet-RSX remote file access capabilities. Edit 
the ODL file created by the compiler. The following is an example of a task using the 
CMD and ODL files. This task uses the defaults for the buffer size ($NFRSZ), the 
number of buffers ($NFNMB), and only one link. The underlined items indicate the 
edits required for the task builder to include remote file access capabilities in the 
task. Boldface items are necessary for network access. 

FORTRAN Example: 

F I LES ♦ CMD {.B SY : F I LES » SY : F I LES / - S P = S Y : F I LES . LB 5 C i » 1 ] F4 POTS 

LB:[1 ,11NETFQR/LB, NETFQR/LB : NFAFSR 

/ 

EXT5CT=$$FSR1 ;2700 
// 

You enter: 



MCRMKB @FILES 



COBOL Example: 

FI LE3 ♦ CMD 

SY n FILES »SY:FILES/-SP=SY:FILES/MP 

EXTSCT=$$FSR1 s2700 
// 

FILES, ODL 

5MERGED ODL FILE CREATED ON 2S-FEB-S2 AT 1G:54;32 

5C0B0L STANDARD ODL FILE GENERATED ON 2B-FEB-B2 1G!4Bs29 

5COBOBJ=FILE3.0BJ 

5C0BMAIN 

LIBR1 :.FCTRLB:[1 ,1]NETFOR/LB- NETFQR/LB ; NFAFSR 

CBOBJ$s ♦ FCTR SY : C 200 ,200 3 F I LES 
CB0T3*s ♦ FCTR LBsCl , 1 HCOBLIB/LB 
OBJRT*: ♦ FCTR CBOB J$-CB0TS*-LIBR1 

.ROOT OBJRT* 

♦ END 



You enter: 



MCR.5TKB @F I LES 
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BASIC-PLUS-2 Example: 



F I LE3 4 CMD 

SY:FILES/CP/FP »FILES/-SP=SY : FILES/MP 
UNITS = 14 
ASG = TI:13 

ASG = SY:5:B: 7:8:9 : 10: 1 1 : 12 
EXTSCT = $$FSR 1:2700 

// 

F I LES ♦ (DDL 

. ROOT BASIC2-RMSR0T-USER >RMSALL 
USER: ♦ FCTR S Y : F I LES - NETLIB 

L I BR : ♦ FCTR LB : C 1 1 1 ] B P20TS / LB 

NETLIB: .FCTR LB:[1,11NETF0R/LB- NETFQR/LB : NFAFSR 

@LB: [ 1 »1 1BP2IC1 
@LBs [1 »1]RMS11X 

♦ END 



You enter: 

MCR >TKB iFILES 



3.8.6 Using ASCII Zero (ASCIZ) Strings 

Some of the network file access subroutines require that you provide one or more 
arguments in the CALL statement as ASCIZ strings. An ASCIZ string is a string of 
ASCII characters terminated by a binary (0). 

You can create an array/numeric data item, store the string in the array/numeric data 
item, then set the last element to zero (0). 

FORTRAN Example: 

DIMENSION IFILE (12) 

DATA IFILE/ 'DK ' » '0: ' t ' [ 1 ' » ' >4 ' » ' 1C ' t 
' N ' > ' TR ' t'OL' >'*A' » ' LG ' > ' 52'/ 
IFILE( 12) = 

You then specify the array name in the CALL statement: 
CALL OPRNFW ( lun tstatus tnode > 1 1 F I LE ) 
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COBOL Example: 

01 NULL 1 PIC 9 COMP VALUE 0. 
01 NULLS REDEFINES NULL 1 . 

03 NULL OCCURS 2 TIMES PIC X(l>. 
01 IFILE PIC X<23) VALUE " DKO : C 200 t200 1 1 NAME ♦ CBL ? 1 " 

♦ 
♦ 

STRING IFILE 
NULL (1) 

INTO I DENT ♦ 

You then specify the string in the CALL statement: 
CALL "OPRNFW" USING lun,status,node,ident ♦ 
BASIC-PLUS-2 Example: 

I F I LE$ = " DKO : C 200 1 200 ] NAME ♦ B2S H " +CHAR* ( 01 ) CHAR* ( 01 ) 

You then specify the array name in the CALL statement: 

CALL OPRNFW BY REF (LUN% tstatusVA ) mode* ndent% >ifile%) 

3.8.7 Common Argument Definitions for Remote File Access Calls 

Arguments commonly used for remote file access calls are defined on the following 
pages to avoid needless repetition throughout the call descriptions. Argument defini- 
tions here are divided into four categories: a general category containing argument 
definitions common to all languages, and three individual language categories for 
arguments with language-specific definitions. 
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GENERAL 

• lun 

is an integer variable or constant that specifies the logical unit number of the logical 
link created for a specific file access operation. 

• node 

specifies the name of the node to which the call is directed. It is a 1- to 7- element 
array/string that ends with a binary and contains a 1- to 6-character ASCIZ string. 

• ident 

contains three successive ASCIZ strings: the user ID, password, and account num- 
ber necessary to access remote node files. It is a 1- to 43. -element ASCIZ array. 

Enter a null value (0) for each item not required by the remote node or each item 
previously entered. For example, you may have already entered the required infor- 
mation in an alias node name block. 

• ifile 

is a byte array/string containing a variable length ASCIZ string that contains the 
file specification for a file access operation. Be sure to use the remote node's file 
specification syntax. 

FORTRAN 

• References to integers imply single-precision integer values. 

• status 

specifies an array that will contain completion status information on return from 
the call. This 2-element single-precision integer array will contain the following 
values when the call completes: 

status(l) returns an error completion code. Refer to Table C-l in Appendix C. 
status(2) depends on the content of the first status word. Refer to Appendix C. 

COBOL 

• For DECnet COBOL, the logical unit number 1 is a reserved number and should 
never be assigned for the lun argument. 

• status 

specifies an elementary numeric data item that will contain completion status 
information on return from the call. This elementary numeric data item will contain 
the following values when the call completes: 

status(l) returns an error completion code. Refer to Table C-l in Appendix C. 
status(2) depends on the content of the first status word. Refer to Appendix C. 
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BASIC-PLUS-2 

• status%() 

specifies an array that will contain completion status information on return from 
the call. This 2-element integer array will contain the following values when the call 
completes: 

status%(0) returns an error completion code. Refer to Table C-l in Appendix C. 
status%(\) depends on the content of the first status word. Refer to Appendix C. 
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ACONFW 



Set Access Options 



3.8.8 ACONFW - Set Access Options 
Use: 

Call ACONFW before a specific file operation to specify record and file access 
options you want applied to that file operation. These options remain in effect 
until the file is closed. 

Formats: 

FORTRAN: CALL ACONFW (lun,[fac],[shrl,lfop],[accopt) 
COBOL: CALL "ACONFW" USING lun,[fac],[shr],[fop]. 
BASIC: CALL ACONFW BY REF (lun%,[fac%],[shr%],[fop%()]) 
Arguments: 
lun 

specifies the logical unit number of the logical link assigned to the file operation 
you want to set options for. 

fac 

specifies the file access operations to be allowed while accessing the file. Use this 
argument only for open and create operations. The fac value overrides the specific 
OPxNFW call used. Valid values are: 

NF$PUT Put access 

NF$GET Get access (default) 

NF$DEL Delete record access 

NF$UPD Update record access 

NF$TRN Truncate file access 

NF$BIO Block I/O 

NF$REA Block I/O read 

NF$WRT Block I/O write 
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shr 

specifies the file sharing to be allowed by the remote system. Use this argument 
only for open and create operations. The actual functioning is dependent on 
remote system capabilities. Valid values are: 

NF$PUT Put access 
NF$GET Get access (default) 
NF$DEL Delete record access 
NF$UPD Update record access 
NF$NIL No access to others 

fop 

specifies a 3-word array for file-processing options to be used for open, create, and 
close operations. To specify a fop value for close operations, the ACONFW call 
must be made after the file has been opened, because the open call will overwrite 
the current value. Valid values are: 

First word: 

NF$CTG Create contiguous file 

NF$SUP Supercede existing file 

NF$TMP Create temporary file 

NF$MKD Create temporary file and mark for delete 

Second word: 

NF$MXV Maximize version number on create 
NF$SPL Spool on close 
NF$EXC Execute on close 
NF$DLC Delete on close 
NF$TEF Truncate on close 

Completion of open/create operations returns: 

First word: 

NF$FLK File is locked 

NF$CTG File is contiguous 

NF$DIR File is a directory (system dependent) 
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ATTNFW 



Set Extended Attributes 



3.8.9 ATTNFW - Set Extended Attributes 
Use: 

Use ATTNFW to specify extended attributes to be used by create, open, and close 
operations. These attributes will be returned to the caller after the specified 
operation completes. 

Call ATTNFW immediately before file create operations (OPWNFW, SPLNFW, 
and SUBNFW) to specify additional attributes when creating the file. 

Call ATTNFW immediately before file open operations (OPRNFW, OPANFW, 
and RENNFW) to specify additional attributes to be returned when opening the 
file. 

Call ATTNFW immediately before file close operations to specify a change-at- 
tributes-on-close sequence. 

Formats: 

FORTRAN: CALL ATTNFW (lun,[namesize],[name],[atb], 

[protblk] , [owner] , [datemenu] , [dateblk] ) 

COBOL: CALL "ATTNFW" USING lun,[namesize],[namel,[atb],[protblk], 

[owner] , [datemenu] , [dateblk] . 

BASIC: CALL ATTNFW BY REF (lun%,[namesize%],[name$],[atb%()], 

[protblk%()],[owner$],[datemenu%], 
[dateblk%()]) 

Arguments: 

lun 

specifies the logical unit number of the logical link for the specified file operation. 
namesize 

specifies the maximum length of the array/string that can be returned to the 
resultant file specification. Use this single-word argument for open and create 
operations. 

* name 

specifies the array/string containing the resultant file name. This argument can 
be used for all operations. The returned file name will be an ASCIZ string. 
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* atb 



specifies a Files-11 user file attributes block. When specifying create operations, 
the user program is responsible for setting valid values because the NFARs will 
not check these values. 

NOTE 

If atb is specified, the ichar(2), ichar(S), and len arguments will be 
ignored when used with open or create calls. Use the fields NF$ORG, 
NF$RAT, and NF$MRS, instead. 

When specifying create and open operations, atb returns a 10. word block in the 
following format: 



RECORD ATTR. 


FILE ORG./REC FMT 


NF$ORG 


LONGEST RECORD LENGTH 


NF$LRL 


HIGHEST VBN ALLOCATED (high word) 


NF$HBK 




(low word) 




,END-OF-FILE VBN 


(high word) 


NF$EBK 




(low word) 




FIRST FREE BYTE 


NF$FFB 


FIXED CTR. SIZE 


BUCKET SIZE 


NF$BKS 


MAXIMUM RECORD SIZE 


NF$MRS 


DEFAULT EXTEND QUANTITY 


NF$DEQ 
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For further information on the values of these fields, see the IAS/RSX I/O Operations 
Reference Manual, Appendixes A and F. 

* protblk 

specifies an array containing file protection information to be used for input for 
create and close operations, and returns information from create and open opera- 
tions. The following format describes a 5- word array: 



FILE OWNER STRING SIZE 



SYSTEM PROTECTION MASK 



OWNER PROTECTION MASK 



GROUP PROTECTION MASK 



WORLD PROTECTION MASK 



If the file owner size is 0, the owner string will not be returned. 

The format of the protection masks is described as follows: 

Bit = Deny read access 

Bit 1 = Deny write access 

Bit 2 = Deny execute access 

Bit 3 = Deny delete access 

Bit 4 = Deny append access 

Bit 5 = Deny directory list access 

Bit 6 = Deny update access 

Bit 8 = Deny change protection access 

Bit 9 = Deny extend access 

If a word is set to a -1, that protection will not be sent. 
owner 

specifies an ASCIZ string/array identifying the file owner to be used for input for 
create operations and for output from create and open operations. The maximum 
size of this string/array must be specified in the first word of the protblk array. 

datemenu 

specifies which values in the date block are to be used for input for create and 
close operations or those values returned on output from create and open opera- 
tions. Valid values are: 

Bit = Revision number 

Bit 1 = Revision date and time 

Bit 2 = Creation date and time 

Bit 3 = Expiration date 
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dateblk 



specifies an 18-word array containing the date, time, and revision information 
associated with the file. Files-11 timestamps are stored in ASCII in the format 
DDMMMYYHHMMSS, and have the following restrictions: leading zeros are 
shown, and MMM is the 3-letter month abbreviation in uppercase letters. The 
following format shows dates in a block: 



NF$RTI 



REVISION NUMBER 



REVISION DATE 



REVISION TIME 



NF$RVN 
NF$RDT 



NF$CDT 



CREATION DATE 




NF$CTI 



NF$EDT 



EXPIRATION DATE 



(not used) 



For further information on the format of dates in a block, see the IAS/RSX I/O 
Operations Reference Manual Appendix F. 
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CLSNFW 



Close a File 



3.8.10 CLSNFW - Close a File 

Use: 

Call CLSNFW to close a remote file. CLSNFW forces completion of all pending 
file operations, ensures the file directory information is valid, optionally modifies 
the attributes specified by the changeattr argument and a previous ATTNFW 
call, and frees the logical unit number when the call completes. 

NOTE 

Some systems do not support the change attribute on close capabil- 
ity. 

Formats: 

FORTRAN: CALL CLSNFW (lun, status, [changeattr]) 
COBOL: CALL "CLSNFW" USING lun, status, [changeattr]. 
BASIC: CALL CLSNFW BY REF {lun%,status%{),[changeattr%]) 
Arguments: 
lun 

specifies the logical unit number of the logical link you want to close. See defini- 
tion in Section 3.8.7. Use the same LUN specified in the previous open call. 

* status 

specifies completion status information on return from CLSNFW. See definition 
for your language in Section 3.8.7. Refer to Table C-l in Appendix C for a 
complete code list. 

changeattr 

specifies the attributes to be changed when this file is closed. The attributes must 
have been specified by a previous ATTNFW call either at open time or just prior 
to this call. Valid values are: 

NF$PRC Change protection 
NF$DTC Change dates and times 
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DELNFW 



Delete a File 

3.8.11 DELNFW - Delete a File 
Use: 

Call DELNFW to delete a remote file. 
Formats: 

FORTRAN: CALL DELNFW (lun,status,node,ident,ifile) 
COBOL: CALL "DELNFW" USING lun,status,node,ident,ifile. 
BASIC: CALL DELNFW BY REF {lun c <>, status <{),node%,ident$, if ile$) 

Arguments: 

lun 

specifies the logical unit number of the logical link you want to delete. See 
definition in Section 3.8.7. 

* status 

specifies completion status information on return from DELNFW. See definition 
for your language in Section 3.8.7. Refer to Table C-l in Appendix C for a 
complete code list. 

node 

specifies the name of the node for the file you want to delete. See definition in 
Section 3.8.7. 

ident 

is an array/string containing access control information. See definition in Section 
3.8.7. 

ifile 

specifies an ASCIZ string containing the file specification for the file to be de- 
leted. See definition in Section 3.8.7. 
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EXENFW 



Execute a File 

3.8.12 EXENFW - Execute a File 
Use: 

Call EXENFW to submit an existing remote file to the batch or command file 
processor. The remote file is not deleted after completion of this call. 

Formats: 

FORTRAN: CALL EXENFW (lun,status, node, ident, ifile) 

COBOL: CALL "EXENFW" USING lun,status,node,ident,ifik. 

BASIC: CALL EXENFW BY REF (lun%,status%(),node$,ident$,ifile$) 
Arguments: 

lun 

specifies the logical unit number of the logical link you want to execute. See 

definition in Section 3.8.7. 

* status 

specifies completion status information on return from EXENFW. See definition 
for your language in Section 3.8.7. Refer to Table C-l in Appendix C for a 
complete code list. 

node 

specifies the name of the node for the file you want to execute. See definition in 
Section 3.8.7. 

ident 

is an array/string containing access control information. See definition in Section 
3.8.7. 

ifile 

specifies an ASCIZ string containing the file specification for the file to be exe- 
cuted. See definition in Section 3.8.7. 
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GETNFW 



Read a Single Record 

3.8.13 GETNFW - Read a Single Record 
Use: 

Call GETNFW to read a record from a file. The record is stored in an array/string 
that you specify in the inarray argument for FORTRAN programmers or the 
instring argument for COBOL and BASIC programmers. Each successive 
GETNFW call reads the record into the same array/string. The previous record is 
overlaid and is no longer available in the user record storage area. 

If the optional rac argument is not specified, the default will be sequential record 
transfer (NR$RTM). The records will be read sequentially from the first record in 
the file. 

If a rac argument is given and specifies random access, the keyptr argument must 
specify the record to be read. 

If an error occurs while a file is being read, the logical link is maintained. You 
must call CLSNFW to close the file. 

Formats: 

FORTRAN: CALL GETNFW (lun, status, inbytes, inarray , 

[seqno], [rac],[keyptr],[rop]) 

COBOL: CALL "GETNFW" USING lun, status, inchars, 

instring, [seqno] , [rac] , [keyptr] , [rop] . 

BASIC: CALL GETNFW BY REF [lun%,status%{),inchars%,instring%, 

[seqno%],[rac%],[keyptr%()],[rop%{)]) 

Arguments: 

lun 

specifies the logical unit number of the logical link created for reading your 
records. See definition in Section 3.8.7. Use the same LUN you assigned in the 
OPRNFW, OPMNFW, or OPUNFW call. 

* status 

specifies completion status information on return from GETNFW. The second 
word contains the byte count length of the record returned. See definition for your 
language in Section 3.8.7. Refer to Table C-l in Appendix C for a complete code 
list. 
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inbytes/inchars 

specifies the length in bytes/characters of inarray Unstring. It is an integer variable 
or constant. The actual length of the record read is returned in the second status 
word. 

inarray/ ins tring 

specifies the array/string that will contain the record to be read from the file. If 
the record size is larger than the integer you specified in inbytes/inchars, the 
balance of the record is lost. 

seqno 

specifies the sequence number for the record to be read from the file. You must 
specify this integer variable for sequenced variable length records. If the record 
type is not sequenced variable length (or in RMS terms, variable with fixed 
control, VFC) the seqno argument is ignored. Be sure to specify the record type in 
the ichar argument of an open call. 

rac 

specifies the record access mode to be used while accessing the file. Use this 
single- word argument only for open/create operations. Once a file transfer mode is 
selected, the rac value will be ignored until the end-of-file is detected. Valid 
values are: 

NR$SEQ Sequential by record 

NR$KEY Random by relative record number (RRN) 

NR$RFA Random by record file address (RFA) 

NR$RTM Sequential file transfer by records (default) 

NR$VBN Random blocks by virtual block number (VBN) 

NR$BTM Sequential file transfer by blocks 

keyptr 

specifies the record. The length is assumed from the rac argument value. 
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RAC Key 

NR$KEY Two-word binary value of RRN 

Low-order word first 
NR$RFA Three-word binary RFA 

Low-order word first 
NR$VBN Two-word binary value of VBN 

Low-order word first 



rop 

specifies record processing options. Valid values are: 

NR$EOF Position to EOF 
NR$UIF Update if existing record 
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OPANFW 



OPMNFW 
OPRNFW 
OPUNFW 



3.8.14 OPANFW - Open a File for Appending Records 

OPMNFW - Open a File for Modifying Records 
OPRNFW - Open a File for Reading Records 
OPUNFW - Open a File for Updating Records 
OPWNFW - Create and Open a File for Writing Records 

See Section 3.8.18. 

Use: 

Call one of the following subroutines to open an existing file: 

Call OPANFW to open a sequential file for appending records. 
Call OPMNFW to open and modify a sequential file. 
Call OPRNFW to open a sequential file for reading records. 
Call OPUNFW to open and update a sequential file. 
Formats: 



FORTRAN: CALL 



[OPANFW J (lun,status,node,ident, 
J OPMNFW ^ ifile,ichar,len,[iblock]) 
1 OPRNFW 



J 



COBOL: 



BASIC: 



CALL 



I^OPUNFW 

r "OPANFW" 
"OPMNFW" 
"OPRNFW" 
"OPUNFW" 



USING lun, status, node, ident, 
ifilejchar^en^iblock]. 



CALL C 3PANFW " 
J OPMNFW 
\ OPRNFW 
^OPUNFW 



J 



BY REF (lun%,status%(),node$,ident$, 
if ile$,ichar$,len%, [iblock]) 
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Arguments: 

lun 

specifies the logical unit number of the logical link created for the OPANFW, 
OPMNFW, OPRNFW, or OPUNFW call. Use the same LUN for any succeeding 
PUTNFW, PRGNFW, or CLSNFW call. See definition in Section 3.8.7. 

* status 

specifies completion status information on return from OPANFW, OPMNFW, 
OPRNFW, or OPUNFW. See definition for your language in Section 3.8.7. Refer 
to Table C-l in Appendix C for a complete code list. 

node 

specifies the name of the node for the file you want to open. See definition in 
Section 3.8.7. 

ident 

is an array/string containing access control information. See definition in Section 
3.8.7. 

ifile 

specifies an ASCIZ string containing the file specification for the file to be 
opened. See definition in Section 3.8.7. 

* ichar 

is a 3-element array/string. If the values you specify differ from those stored in the 
file, the stored values are used. When the open call completes, the ichar 
array/string contains the stored values. Check these values to see how the file was 
actually opened. Make sure you specify the appropriate ASCII letter code as 
defined in the following three fields: 

ichar (1) - Mode 

Letter Code Description 

A ASCII file 

I Binary image file 
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ichar(2) - Record Format 



Letter Code 



Description 



U 
F 
V 
S 
A 



Undefined format records 

Fixed length records 

Variable length records 

Sequenced variable length records (VFC) 

ASCII stream format 



ichar(3) - Carriage Control 



Letter Code 



Description 



F 
T 
N 
P 



FORTRAN carriage control 
Terminal carriage control 
No carriage control 
Print file VFC 



The following example displays one method for the ichar argument. In this exam- 
ple, ichar specifies the file to be opened as an ASCII file ('A'), with variable length 
records ('V'), and FORTRAN style carriage control ('F'). 

Example: 

BYTE ICHAR (3) 

DATA ICHAR/ 'A ' » 'U ' » 'F V 

ICHAR PIC XXX VALUE " AUF " ♦ (COBOL) 

I CH AR$ = " AMF " (BASIC) 



is an integer variable that specifies record length. If the file has variable length 
records, enter the maximum record length. A null value (0) implies there is no 
maximum record length. 



is an integer variable that returns the number of blocks currently allocated to the 
file. The values are described as follows: 



* 



len 



* 



iblock 



Entry 



Description 



+n 



Number of noncontiguous blocks 
(where n = number of blocks) 



-n 



Number of contiguous blocks 
(where n = number of blocks) 
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PRGNFW 



Discard an Opened File 

3.8.15 PRGNFW - Discard an Opened File 
Use: 

Call PRGNFW to close a remote file because one or more errors occurred in the 
transfer. If the file was newly created by an OPWNFW, SPLNFW, or SUBNFW 
call, it is deleted. If the file existed previously and was just opened by an 
OPRNFW or OPANFW call, it is closed in its current state. 

Formats: 

FORTRAN: CALL PRGNFW (lun,status) 
COBOL: CALL "PRGNFW" USING lun,status. 
BASIC: CALL PRGNFW BY REF {lun%,status%{)) 
Arguments: 

lun 

specifies the logical unit number of the logical link you want to close. See defini- 
tion in Section 3.8.7. Use the same LUN specified in the previous open call. 

* status 

specifies completion status information on return from PRGNFW. See definition 
for your language in Section 3.8.7. Refer to Table C-l in Appendix C for a 
complete code list. 
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PUTNFW 



Write a Single Record 



3.8.16 PUTNFW - Write a Single Record 
Use: 

Call PUTNFW to write a record to a file. PUTNFW writes the indicated number 
of bytes/characters from the array/string you specify in the outarray/outstring 
argument. 

If the optional rac argument is not specified, the default will be sequential record 
transfer (NR$RTM). The records will be written sequentially beginning at the 
first record position unless the file was opened with an OPANFW call, in which 
case they are written after the last record. 

If a rac value is given and specifies random access, the keyptr argument must 
specify the record position where the record will be written. 

If a PUTNFW call returns an error, you can close the output file with either a 
PRGNFW or CLSNFW call, or you can continue the write (PUTNFW) operation. 

Formats: 

FORTRAN: CALL PUTNFW (lun,status,outbytes,outarray, 

[seqno] , [rac] , [keyptr] , [rop] ) 

COBOL: CALL "PUTNFW" USING lun,status,outchars,outstring, 

[seqno] , [rac] , [keyptr] , [rop] . 

BASIC: CALL PUTNFW BY REF (lun%,status%(),outchars%,outstring$, 

[seqno%],[rac%],[keyptr%{)],[rop%{)]) 

Arguments: 

lun 

specifies the logical unit number of the logical link created for writing a single 
record. See definition in Section 3.8.7. Use the same LUN you assigned in the 
OPANFW, OPMNFW, OPUNFW, SPLNFW, SUBNFW, or OPWNFW call. 

* status 

specifies completion status information on return from PUTNFW. See definition 
for your language in Section 3.8.7. Refer to Table C-l in Appendix C for a 
complete code list. 
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outbytes/outchars 

specifies the number of bytes/characters to be written to the file from the 
outarray/outchars argument. This integer variable or constant must be equal to or 
less than the maximum record length you specified in the open call. If data 
overrun occurs, the remaining bytes are lost. 

outarray/outstring 

is the name of the array/string that contains the record to be written to the file. 
seqno 

specifies the sequence number of the record to be written. You must specify this 
integer variable or constant for sequenced variable length records. If the record 
type is not sequenced variable length (or in RMS terms, variable with fixed 
control, VFC), the seqno argument is ignored. Remember to specify the record 
type in the ichar argument of an open call. 

rac 

specifies the record access mode to be used while accessing the file. Use this 
single- word argument only for open/create operations. Once a file transfer mode is 
selected, the rac value will be ignored until after end-of-file is detected. Valid 
values are: 

NR$SEQ Sequential by record 

NR$KEY Random by relative record number (RRN) 

NR$RFA Random by record file address (RFA) 

NR$RTM Sequential file transfer by records (default) 

NR$VBN Random blocks by virtual block number (VBN) 

NR$BTM Sequential file transfer by blocks 

keyptr 

specifies the record. The length is assumed from the rac argument value. 
RAC Key 

NR$KEY Two- word binary value of -RRN 

Low- order word first 
NR$RFA Three-word binary RFA 

Low-order word first 
NR$VBN Two-word binary value of VBN 

Low-order word first 

rop 

specifies record-processing options. Valid values are: 

NR$EOF Position to EOF 
NR$UIF Update if existing record 
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RENNFW 



Rename a File 

3.8.17 RENNFW - Rename a File 
Use: 

Call RENNFW to rename a remote file. 
Formats: 

FORTRAN: CALL RENNFW (lun,status, node, ident, ofile, nfile) 

COBOL: CALL "RENNFW" USING lun,status,node, 

ident, ofile,nfile. 

BASIC: CALL RENNFW BY REF (lun%,status%Q,node$, 

ident$,ofile§,nfile§) 

Arguments: 

lun 

specifies the logical unit number of the logical link created for renaming a remote 
file. See definition in Section 3.8.7. 

* status 

specifies completion status information on return from RENNFW. See definition 
for your language in Section 3.8.7. Refer to Table C-l in Appendix C for a 
complete code list. 

node 

specifies the name of the node for the file you want to rename. See definition in 
Section 3.8.7. 

ident 

is an array/string containing access control information. See definition in Section 
3.8.7. 

ofile 

specifies an ASCIZ array/string containing the file to be renamed. 
nfile 

specifies an ASCIZ array/string containing the new file specification for the newly 
renamed file. 

NOTE 

If a name buffer is attached via ATTNFW, the resultant file specifi- 
cation of the new file will be returned in that name buffer. 
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SPLNFW 



SUBNFW 
OPWNFW 



3.8.18 SPLNFW - Create, Write, and Print a File 

SUBNFW - Create, Write, and Execute a File 
OPWNFW - Create and Open a File for Writing Records 

Use: 

Call one of the following subroutines to create a file: 

Call SPLNFW to create a new remote file, write to it, and print it at the 
remote node. 

Call SUBNFW to create a new remote file, write to it, and submit it to the 
remote batch/command file processor for execution. The file is 
deleted after execution. 

Successful completion of SUBNFW does not mean that the file 
ran properly or even that it ran at all. Successful completion of 
this call implies only that the file was handled properly by the 
remote node. 

Call OPWNFW to create and open a sequential file for writing records. 



Formats: 

FORTRAN: CALL 



COBOL: 



BASIC: 



CALL 



CALL 



'SUBNFW 
^ SPLNFW 
OPWNFW 



"SUBNFW"^ 

"SPLNFW" 

"OPWNFW" 
_y 

SUBNFW^ 
SPLNFW 
OPWNFW 



(lun, status, node, ident, 
ifile,ichar,len,[iblock]) 

USING lun, status, node, ident, 
ifile,ichar,len,[iblock]. 

BY REF {lun%,status%{),node%,ident%, 
ifile$,ichar$,len%,[iblock%}) 
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Arguments: 

lun 

specifies the logical unit number of the logical link for the SPLNFW, SUBNFW, 
or OPWNFW, call. Use the same LUN for any succeeding PUTNFW, PRGNFW, 
or CLSNFW call. See definition in Section 3.8.7. 

* status 

specifies status completion information on return from SPLNFW, SUBNFW, or 
OPWNFW. See definition for your language in Section 3.8.7. Refer to Table C-l 
in Appendix C for a complete code list. 

node 

specifies the name of the node for the file you want to open using SPLNFW, 
SUBNFW or OPWNFW. See definition in Section 3.8.7. 

ident 

is an array/string containing access control information. See definition in Section 
3.8.7. 

ifile 

specifies an ASCIZ string containing the file specification for the file to be opened 
using SPLNFW, SUBNFW, or OPWNFW. 

* ichar 

is a 3-element array/string. If the values you specify differ from those stored in the 
file, the stored values are used. When the open call completes, the ichar 
array/string contains the stored values. Check these values to see how the file was 
actually opened. Make sure you specify the appropriate ASCII letter code as 
defined in the following three fields: 

ichar (1) - Mode 

Letter Code Description 

A ASCII file 

I Binary image file 
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ichar(2) - Record Format 

Letter Code Description 

U Undefined format records 

F Fixed length records 

V Variable length records 

S Sequenced variable length records (VFC) 

A ASCII stream format 

ichar(S) - Carriage Control 

Letter Code Description 

F FORTRAN carriage control 

T Terminal carriage control 

N No carriage control 

P Print file VFC 

The ichar array/string specifies values for the new file. 

len 

is an integer variable that specifies record length. If record lengths vary, enter the 
maximum record length. A null value (0) implies there is no maximum record 
length. 

iblock 

is an integer variable that specifies the number of blocks you want to allocate for 
file creation. Enter one of the following values: 

Entry Description 

Dynamic allocation 

+n Number of noncontiguous blocks 

(where n = number of blocks) 

-n Number of contiguous blocks 

(where n = number of blocks) 

When SPLNFW, SUBNFW, or OPWNFW completes, iblock specifies the num- 
ber of blocks allocated (if you specified a +n or a -n argument, or (if you 
specified dynamic allocation). 

If the system cannot allocate the number of requested blocks, an error returns and 
frees the LUN. If you omit the iblock argument, the system allocates space dy- 
namically. 
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3.8.19 FORTRAN Remote File Access Programming Example (Append) 



The program FTNAPP appends the contents of a local ASCII file to the end of a 
remote ASCII file and then closes both files. If an error occurs, the program displays 
an error message. In the following example, the user ID is FRED, the password is 
PRIV, and the account number is 1. 

NOTE 

This programming example is also included in your tape or disk kit. 



c 

C THIS PROGRAM IS A VARIATION OF THE PROGRAM THAT APPEARS IN THE 

C RSX DECNET PROGRAMMER'S REFERENCE MANUAL 

C 

C TO TASK BUILD USE THE FOLLOWING COMMAND STRING: 
C 

C FTNAPP , FTNAPP= FTNAPP ,[1,1] NETFOR/LB , F4POTS/LB , RMSL I B/LB , NETFOR/LB : NFAFSR 
C / 

C UNITS=10 

C EXTSCT=$$FSR1:2700 

C ACTFIL=4 

C EXTTSK=1000 (if RMS included) 

C // 

C 

C 

BYTE NODE(7) , BUFFER ( 128 ) , IDENT(30) , I CHAR ( 3 ) 

INTEGER ISTAT(2) , JSTAT(2) ,KSTAT(2) , LSTAT ( 2 ) , MSTAT ( 3 ) , NSTAT ( 2 ) 
DATA ICHAR/'A' ,'F'/ 

C 

C GET USER ID, PASSWORD AND ACCOUNT 

C 

TYPE 666 

666 FORMAT ( ' $ ENTER USER I .D. : ' ) 
ACCEPT 779, ICNT, ( IDENT( I ) , 1=1 , ICNT) 
IDENT(ICNT+1)=0 

TYPE 667 

667 FORMAT ( ' $ENTER PASSWORD: ') 

ACCEPT 779, ICNT9 , ( I DENT ( I ) , I=ICNT+2 . ICNT+2+ICNT9-1 ) 
I DENT ( ICNT+ 2 + I CNT9 ) =0 
TYPE 668 

668 FORMAT ( ' $ ENTER ACCOUNT NUMBER: ') 
K=ICNT+l+ICNT9+2 

ACCEPT 779,1 CNT 8,(1 DENT ( I ) , I =K , K + I CNT8 - 1 ) 
779 FORMAT (Q,10Al) 

TYPE *, 'IDENT = ' , ( IDENT( I ) , 1=1 , 15) 
TYPE *, (IDENT(I),I=16,30) 

C 

C GET REMOTE NODE NAME LOCAL AND REMOTE FILE SPECS 

C 

95 TYPE 100 

100 FORMAT ( ' $ ENTER REMOTE NODE NAME (6 CHAR. MAX.):') 

ACCEPT 110 , I CNT 3 , ( NODE ( I ) , 1=1 , ICNT3) 
110 FORMAT (Q,6A1) 

IF (ICNT3-6) 115,115,95 
115 TYPE *,'NODE NAME = ' , ( NODE (I), 1=1, 7) 

TYPE 120 

120 FORMAT ( ' $ ENTER FILE SPEC. OF REMOTE FILE FOR APPEND:*) 

ACCEPT 130,1 CNT 1 , ( BUFFER ( I ) , I = 1 , I CNT 1 ) 
130 FORMAT (Q,64A1) 

BUFFER(ICNT1+1)=0 

TYPE 140 

(continued on next page) 
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140 FORMAT ( ' $ ENTER FILE SPEC. OF LOCAL FILE TO BE APPENDED:*) 

ACCEPT 150 , ICNT2 , (BUFFER( I ) f 1=64 , 63+ICNT2 ) 
150 FORMAT (Q,64A1) 

BUFFER(ICNT2+64)=0 

C 

C CREATE NETWORK MAILBOX FOR ONLY ONE LINK 

C 

CALL OPNNTW ( 2 , LSTAT , MSTAT , 1 ) 
IF (LSTAT(l)-l) 907,160,907 

C 

C OPEN LOCAL AND REMOTE FILES 

C 

160 OPEN (UNIT=4,NAME=BUFFER(64) ,TYPE='OLD' ,ERR=901) 

CALL OPANFW (1,1 STAT , NODE , I DENT , BUFFER , I CHAR , LENGTH , I BLOCK ) 
IF (ISTAT(l)-l) 908,200,908 

C 

C READ RECORDS FROM LOCAL FILE AND WRITE THEM TO REMOTE FILE 

C 

200 READ (4,210,END=300,ERR=902) ICNT3 , (BUFFER( I ) , 1=1 , ICNT3 ) 

210 FORMAT (Q,128A1) 

CALL PUTNFW ( 1 ,JSTAT, ICNT3 , BUFFER) 

IF (JSTAT(l)-l) 903,200,903 

C 

C EOF FOUND -- CLOSE BOTH FILES AND NET 

C 

300 CLOSE (UNIT=4,ERR=904) 

CALL CLSNFW ( 1 , KSTAT ) 

IF (KSTAT(l)-l) 905,310,905 
310 CALL CLSNTW ( NSTAT ) 

IF (NSTAT(l)-l) 906,320,906 
320 STOP 'APPEND O.K.' 

C 

C ERROR HALTS 

C 

901 TYPE*, (BUFFER(I) , 1=1,63) 
TYPE*, (BUFFER(I) , 1=64,128) 
STOP 'CAN NOT OPEN LOCAL FILE' 

902 STOP 'READ ERROR FROM LOCAL FILE* 

903 TYPE *, 'STATUS =',JSTAT(1) 

STOP 'WRITE ERROR FROM REMOTE FILE* 

904 STOP 'CAN NOT CLOSE LOCAL FILE' 
90 5 TYPE * , ' STATUS = ' , KSTAT ( 1 ) 

STOP 'CAN NOT CLOSE REMOTE FILE' 

906 STOP 'CAN NOT CLOSE NETWORK ' 

907 TYPE * , ' STATUS = ' , LSTAT ( 1 ) 
STOP 'MAILBOX CREATION ERROR' 

908 TYPE *,' STATUS =' , ISTAT( 1 ) , ISTAT( 2 ) 
STOP 'CAN NOT OPEN REMOTE FILE* 

C 

END 
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3.8.20 FORTRAN Remote File Access Programming Example 
(Read/Write) 

The program FTNRRW reads the contents of one remote file into another remote file. 
When an end-of-file is encountered, the last record is written to the remote file and 
both files are closed. If a read or write error occurs a message is displayed and the 
program exits. In the following example, the user ID is JOE, the password is PRIV, 
and the account number is 404. 

NOTE 

This programming example is also included in your tape or disk kit. 



C read from a remote file and write to a remote file using 

C decnet fortran remote file access support 

C 

C To task build use the following command string: 
C 

C FTNRRW , FTNRRW= FTNRRW ,[1,1] NETFOR/LB , F4POTS/LB , RMSL I B/LB , NETFOR/LB : NFAFSR 

C / 

C UNITS=10 

C EXTSCT=$$FSR1: 10000 

C ACTFIL=4 

C EXTTSK=1000 (if RMS included) 

C // 

C 

C 

C declare the necessary data structures 

DIMENS ION I ARRAY ( 2 56 ) , I STAT ( 2 ) , IBLK ( 1 ) , LNTH ( 1 ) 

COMMON I STAT 

LOGICAL*l IDINFO(13) ,ICHARS(3) 

LOGICAL EOF 

DATA EOF/. FALSE./ 

C ASCIZ strings for user ID, password and account number. 

DATA IDINFO/'J' , , O , , , E , ,0, , P , , , R , , , I', , V , ,0, , 4 , , , , , , 4 , f 0/ 
C array containing mode, record type and carriage control information 

DATA ICHARS/'I' , 'V* , *T'/ 

c declare network task 

CALL OPNNTW(7, ISTAT, ,2) 
CALL CKSTAT 

C open two files, one for input and one for output. 

C both of these files exist on a remote node. 

C open file for input 

CALL OPRNFWQ, ISTAT, * IASNOD* , IDINFO, ' 
X [133,224]NET.TST' , I CHARS , LNTH , ) 
CALL CKSTAT 



(continued on next page) 
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C open file for output 

CALL OPWNFW (2,1 STAT , * IASNOD' , IDINFO, ' 
X [133,224]NEWNET.TST' , I CHARS , LNTH , ) 
CALL CKSTAT 

C once the files are successfully opened, we may transfer records. 

C the file associated with lun 1 is opened for reading, the 

C file on lun 2 is opened for writing. 

C transfer files 

DO 30 1=1,100,1 

C get a record from the input file. 

CALL GETNFW (1, 1ST AT, 256, I ARRAY ) 
C status code 050047 is end of file 

IF (ISTAT(I) . NE. 1 .AND. ISTAT(2) . NE. '050047'O) GO TO 40 
LNTH ( 1 ) = ISTAT(2) 

C check for end of file 

IF (ISTAT(I) .NE. 1 .AND. ISTAT(2) .EQ. '050047'O) EOF= . TRUE . 
IF (EOF .EQ. .TRUE.) GO TO 50 

CALL PUTNFW (2,1 STAT , LNTH , I ARRAY ) 

IF (ISTAT(I) .NE. 1 .AND. ISTAT(2) .NE. *050047*O) GO TO 40 
30 CONTINUE 

40 PRINT 41 

41 FORMAT ( 1H1 , ' READ OR WRITE ERROR OCCURRED') 
C close files 

C now that files have been transferred we may close 

C the files 

50 DO 55 1=1,2,1 

CALL CLSNFW (1,1 STAT ) 
55 CONTINUE 

IF (EOF .NE. .TRUE.) GO TO 60 

PRINT 57 

57 FORMAT (1H1, 'END OF FILE REACHED, FILES CLOSED') 

60 STOP 
END 

SUBROUTINE CKSTAT 
DIMENSION ISTAT(2) 
COMMON I STAT 

IF (ISTAT(I) .EQ.l) GO TO 10 

5 FORMAT ( 1H1 , * OPEN ERROR ' ) 

PRINT 5 

STOP 
10 RETURN 

END 
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3.8.21 COBOL Remote File Access Programming Example (Append) 

The program COBAPP appends the contents of a local ASCII file to the end of a 
remote ASCII file and then closes both files. If an error occurs, the program displays 
an error message. 

NOTE 

This programming example is also included in your tape or disk kit. 



IDENTIFICATION DIVISION. 
PROGRAM- ID. COBAPP. 

************************************************ 
* 

* THIS PROGRAM APPENDS THE CONTENTS OF A LOCAL ASCII 

* FILE TO THE END OF A REMOTE ASCII FILE AND THEN 

* CLOSES BOTH FILES. 
* 

* TO TASK BUILD USE THE FOLLOWING COMMAND STRING: 
* 

* COBAPP , COBAPP=COBAPP ,[1,1 ] NETFOR/LB , C81L IB/LB , RMSL IB/LB , NETFOR/LB : NFAFSR 

* / 

* UNITS=10 

* EXTSCT=$$FSR1:2700 

* ACTFIL=4 

* EXTTSK=1000 (if RMS included) 

* // 
* 

* 

****************************************************************************** 

ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER . PDP- 1 1 . 
OBJECT-COMPUTER . PDP- 1 1 . 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT LOCAL-FILE ASSIGN TO "DBO : " . 
DATA DIVISION. 
FILE SECTION. 

FD LOCAL-FILE 

LABEL RECORDS ARE STANDARD 
VALUE OF ID IS LOCAL. 

01 LOCAL-REC PICX(80). 

WORKING- STORAGE SECTION. 
01 MSGS. 

03 MSG1. 

05 FILLER 

05 MSG1-STAT1 
05 FILLER 
05 MSG1-STAT2 
03 MSG 2 . 

05 FILLER 

(continued on next page) 



PIC X(36) VALUE 

"ION ERROR, IOST(l) 
PIC -99999. 

PIC X(ll) VALUE 
PIC -99999. 

PIC X(38) VALUE 



" MAIL BOX CREAT 
" IOST(2) = ". 
" CAN NOT OPEN R 
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01 



01 



05 MSG2-STAT1 
05 FILLER 
05 MSG2-STAT2 
03 MSG3. 

05 FILLER 

05 MSG3-STAT1 
05 FILLER 
05 MSG3-STAT2 
03 MSG4 . 

05 FILLER 

05 MSG 4- STAT 1 
05 FILLER 
05 MSG4-STAT2 
03 MSG5. 

05 FILLER 

05 MSG 5- STAT 1 

05 FILLER 

05 MSG 5 -STAT 2 
ARRAYS . 
03 IOST. 

05 IOST AT OCCURS 
03 MSTAT. 

05 MSTATS OCCURS 
STORE-STUFF. 



" EMOTE FILE, 
PIC -99999. 
PIC X(ll) 
PIC -99999. 



IOST(l) = ". 
VALUE " IOST(2) = 



PIC X(42) VALUE " WRITE ERROR FR 

"OM REMOTE FILE. IOST(l) = ". 
PIC -99999. 

PIC X(ll) VALUE " IOST(2) = ". 

PIC -99999. 



PIC X(39) 
"REMOTE FILE. 



VALUE 
IOST! 



CAN MOT CLOSE 



PIC -99999. 

PIC X(ll) VALUE " IOST(2) 

PIC -99999. 



CAN NOT CLOSE 



PIC X(35) VALUE 
" NETWORK . IOST(l) = 
PIC -99999. 

PIC X(ll) VALUE "IOST(2) = 

PIC -99999. 



2 TIMES PIC S9999 USAGE COMP. 



3 TIMES PIC S9999 USAGE COMP. 



03 


LOCAL 


PIC 


X(26) . 






03 


I DENT 


PIC 


X(30) . 






03 


USERID 


PIC 


X(12) . 






03 


PASSWD 


PIC 


X(6). 






03 


ACCNT 


PIC 


X(9). 






03 


REMOTE- FILE 


PIC 


X(30) . 






03 


FILLER 


PIC 


X. 






03 


OPNLUN 


PIC 


9 


COMP VALUE 


4. 


03 


COUNT1 


PIC 


9 


COMP VALUE 


1. 


03 


APPLUN 


PIC 


9 


COMP VALUE 


3. 


03 


LENGTH 1 


PIC 


S9999 


USAGE COMP. 




03 


BLOCK1 


PIC 


S9999 


USAGE COMP. 




03 


REC- LENGTH 


PIC 


S99 


COMP VALUE 


80. 


03 


NODE-NAME 


PIC 


X(7). 






03 


TEMP-NODE 


PIC 


X(6). 






03 


TEMP-REMOTE 


PIC 


X(29) . 






03 


I CHAR 


PIC 


X(3) 


VALUE " AVF" 




NULL1 


PIC 


9 


COMP VALUE 


6. 



01 

01 NULLS REDEFINES NULL1. 

03 NUL OCCURS 2 TIMES 
PROCEDURE DIVISION. 



PIC X( 1) . 
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***************************************************** 

* * 

* GET ACCOUNTING INFORMATION FOR REMOTE NODE FROM * 

* TERMINAL AND FORM ASCIZ STRING WITH THIS INFORMATION * 

* FOR OPRNFW AND OPWNFW. * 

* * 
***************************************************************** 

Al 00 -START. 

DISPLAY " INPUT USER ID: ". 
ACCEPT USERID. 

DISPLAY " INPUT PASSWORD: ". 
ACCEPT PASSWD. 

DISPLAY " INPUT ACCOUNT NUMBER: ". 
ACCEPT ACCNT. 
STRING USERID 

NUL(l) 

PASSWD 

NUL(l) 

ACCNT 

NUL(l) DELIMITED BY SIZE 
INTO I DENT. 

***************************************************************** 

* * 

* GET REMOTE NODE NAME AND FORM ASCIZ STRING. * 

* * 
***************************************************************** 

DISPLAY " INPUT REMOTE NODE NAME: ". 
ACCEPT TEMP-NODE. 
STRING TEMP-NODE 

NUL(l) DELIMITED BY SIZE 

INTO NODE-NAME. 

***************************************************************** 

* * 

* GET REMOTE FILE NAME AND FORM ASCIZ STRING. * 

* * 
***************************************************************** 

DISPLAY^ ENTER FILE SPEC. OF REMOTE FILE FOR APPEND". 
ACCEPT TEMP- REMOTE. 
STRING TEMP-REMOTE 

NUL(l) DELIMITED BY SIZE 

INTO REMOTE- FILE. 

***************************************************************** 

* * 

* GET LOCAL FILE NAME. * 

* * 
***************************************************************** 

DISPLAY " ENTER FILE SPEC. OF LOCAL FILE TO BE APPENDED". 
ACCEPT LOCAL. 
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************************************************** 

* * 

* ACCESS THE NETWORK. IF THE CALL COMPLETES 

* UNSUCCESSFULLY, WRITE AN ERROR MESSAGE AND EXIT. * 

* * 
***************************************************************** 

CALL "OPNNTW" USING 

OPNLUN 

IOST 

MSTAT 

COUNT 1 . 
IF IOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

MOVE IOSTAT (1) TO MSG1-STAT1 
MOVE IOSTAT (2) TO MSG1-STAT2 
DISPLAY MSG1 
GO E100-END. 

***************************************************************** 

* * 

* OPEN THE LOCAL FILE. OPEN THE REMOTE FILE FOR * 

* APPEND. IF UNABLE TO OPEN THE REMOTE FILE, WRITE * 

* AN ERROR MESSAGE AND DEACCESS THE NETWORK. * 
***************************************************************** 



OPEN INPUT LOCAL- FILE. 
CALL "OPANFW" USING 

APPLUN 
IOST 

NODE-NAME 
I DENT 

REMOTE-FILE 
I CHAR 
LENGTH 1 
BLOCK1 . 
IF IOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

MOVE IOSTAT (1) TO MSG2-STAT1 
MOVE IOSTAT (2) TO MSG2-STAT2 
DISPLAY MSG2 
GO D100-CLOSE. 
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***************************************************************** 

* * 

* READ A RECORD FROM THE LOCAL FILE AND APPEND IT TO * 

* THE REMOTE FILE UNTIL THE END-OF-FILE IS ENCOUNTERED * 

* IN THE LOCAL FILE. IF AN ERROR OCCURS WHILE WRITING * 

* TO THE REMOTE FILE, PRINT AN ERROR MESSAGE AND EXIT. * 

* * 
***************************************************************** 



B100-READ. 

MOVE SPACES TO LOCAL-REC. 
READ LOCAL- FILE RECORD 

AT END GO C100-EOF. 
CALL "PUTNFW" USING 

APPLUN 

IOST 

REC-LENGTH 

LOCAL-REC. 
IF IOSTAT (1) = 1 GO B100-READ. 
MOVE IOSTAT (1) TO MSG 3 -ST ATI. 
MOVE IOSTAT (2) TO MSG3-STAT2. 
DISPLAY MSG 3. 
GO E100-END. 



***************************************************************** 

* * 

* WHEN THE END-OF-FILE IS ENCOUNTERED IN THE LOCAL * 

* FILE, CLOSE THE LOCAL AND REMOTE FILES. IF UNABLE * 

* TO CLOSE THE REMOTE FILE, PRINT AN ERROR MESSAGE * 

* AND EXIT. * 

* * 
***************************************************************** 



C100-EOF. 

CLOSE LOCAL-FILE. 
CALL "CLSNFW" USING 

APPLUN 

IOST. 
IF IOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

MOVE IOSTAT (1) TO MSG4-STAT1 
MOVE IOSTAT (2) TO MSG4-STAT2 
DISPLAY MSG4 

***************************************************************** 

* * 

* DEACCESS THE NETWORK. DISPLAY AN ERROR MESSAGE * 

* IF THE CALL DOES NOT COMPLETE SUCCESSFULLY. * 

* * 
***************************************************************** 



D100-CLOSE. 

CALL "CLSNTW" USING 

IOST. 
IF IOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

MOVE IOSTAT (1) TO MSG 5- STAT 1 
MOVE IOSTAT (2) TO MSG5-STAT2 
DISPLAY MSG 5 
GO E100-END. 

DISPLAY "APPEND COMPLETE. END COBAPP PROGRAM EXECUTION". 
E100-END. 

STOP RUN. 
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3.8.22 COBOL Remote File Access Programming Example 
(Read/Write) 



The program COBRRW reads the contents of one remote file into another remote file. 
When an end-of-file is encountered, the last record is written to the remote file and 
both files are closed. 

NOTE 

This programming example is also included in your tape or disk kit. 



IDENTIFICATION DIVISION. 
PROGRAM- ID. COBRRW. 



****************************************************** 
* 

* THIS PROGRAM READS THE CONTENTS OF A REMOTE FILE 

* INTO ANOTHER REMOTE FILE. EACH RECORD IS READ AND 

* WRITTEN UNTIL END-OF-FILE OCCURS AT WHICH TIME THE 

* LAST RECORD IS WRITTEN TO THE REMOTE FILE AND 

* BOTH FILES ARE CLOSED. 
* 

* TO TASK BUILD USE THE FOLLOWING COMMAND STRING: 
* 

* COBRRW, COBRRW=COBRRW, [ 1 , 1 ]NETFOR/LB ,C81L IB/LB , RMSL IB/LB, NETFOR/LB:NFAFSR 

* / 

* UNITS=10 

* EXTSCT=$$FSR1: 10000 

* ACTFIL=4 

* EXTTSK=1000 (if RMS included) 

* // 
* 

* 

****************************************************************************** 



ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER . PDP- 1 1 . 
OBJECT-COMPUTER . PDP- 1 1 . 
INPUT -OUTPUT SECTION. 
FILE-CONTROL. 

SELECT DUMMY-FILE ASSIGN TO "COBRRW. DUM" . 



DATA DIVISION. 

FILE SECTION. 

FD DUMMY- FILE 

LABEL RECORD STANDARD. 
01 DUMMY-FILE-REC. 

02 FILLER PIC X(132) 

WORKING-STORAGE SECTION. 
01 MSGS. 

03 MSG1. 

05 FILLER 



03 



05 
05 
05 
MSG 2 . 

05 FILLER 



MSG 1- STAT 1 
FILLER 
MSG 1- STAT 2 



PIC X(34) 
"ETWORK. 
PIC -99999. 
PIC X(ll) 
PIC -99999. 

PIC X(44) 



VALUE 
IOST(l) = 



CAN NOT OPEN N 



VALUE " IOST(2) = 



VALUE " CAN NOT OPEN R 
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01 



01 



05 MSG2-STAT1 
05 FILLER 
05 MSG2-STAT2 
3 MSG 3 . 

05 FILLER 

)5 MSG3-STAT1 
3 5 FILLER 
5 MSG 3 -ST AT 2 
3 MSG4 . 

"J5 FILLER 



05 MSG4-STAT1 
05 FILLER 
05 MSG4-STAT2 
3 MSG5. 

05 FILLER 

05 MSG5-STAT1 

05 FILLER 

05 MSG5-STAT2 
ARRAYS . 
03 IOST. 

05 IOST AT OCCURS 2 
3 MSTAT . 

05 MSTATS OCCURS 3 
STORE-STUFF. 



"EMOTE INPUT FILE. 
PIC -99999. 
PIC X(ll) VALUE 
PIC -99999. 

PIC X(45) VALUE 
"SMOTE INPUT FILE. 
PIC -99999. 
PIC X(ll) 
PIC -99999. 



IOST(l) = ". 
" IOST(2) = ". 



" CAN NOT OPEN R 
IOST(l) = ". 



VALUE " IOST(2) 



PIC X( 24 ■ 
"OSTi . • -- '' 

PIC -99999, 
PIC X(ll) 
PIC -99999, 

PIC X(25) 
"IOST(l) = 
PIC -99999, 
PIC XQ1) 
PIC -99999, 



VALUE 



READ 3RRCR . 



VALUE " IOST(2) = " 



VALUE " WRITE ERROR. 



VALUE " IOST(2) = ", 



TIMES PIC S9999 USAGE COMP. 
TIMES PIC S9999 USAGE COMP. 



03 


OPNLUN 


PIC 


9 


COMP VALUE 


2. 


03 


COUNT 1 


PIC 


9 


COMP VALUE 


2. 


03 


LENGTH 1 


PIC 


S9999 


USAGE COMP. 




03 


BLOCK 1 


PIC 


S9999 


USAGE COMP. 




03 


INPLUN 


PIC 


9 


COMP VALUE 


3. 


03 


OUTLUN 


PIC 


9 


COMP VALUE 


4. 


03 


I 


PIC 


999 


USAGE COMP. 




03 


I ARRAY-SIZE 


PIC 


99 


COMP VALUE 


80. 


03 


EOF 


PIC 


99999 


COMP VALUE 


20519 


03 


EOFFG 


PIC 


S9 


USAGE COMP. 




03 


TTRUE 


PIC 


S9 


COMP VALUE 


-1. 


03 


FFALSE 


PIC 


S9 


COMP VALUE 


0. 


03 


I DENT 


PIC 


X(30) . 






03 


USER ID 


PIC 


X(12) . 






03 


PASSWD 


PIC 


X(6) . 






03 


ACCNT 


PIC 


X(9). 






03 


TEMP-NODE 


PIC 


X(6). 






03 


NODE- NAME 


PIC 


X(7). 






03 


TEMP- INPUT 


PIC 


X(29) . 






03 


REMOTE- INPUT 


PIC 


X(30) . 






03 


TEMP-OUTPUT 


PIC 


X(29) . 






03 


REMOTE-OUTPUT 


PIC 


X(30) . 






03 


I CHAR 


PIC 


X(3) 


VALUE " AVF" 




03 


I ARRAY 


PIC 


X(80) . 






NULL1 


PIC 


9 


COMP VALUE 


0. 



01 

01 NULLS REDEFINES NULL1. 

03 NUL OCCURS 2 TIMES 
PROCEDURE DIVISION. 



PIC X(l) . 
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************************************************************ 

* * 

* GET ACCOUNTING INFORMATION FOR REMOTE NODE AND * 

* FORM ASCIZ STRING FOR DECNET REMOTE FILE ACCESS * 

* SUBROUTINES. * 

* * 
*************************************************************** 

Al 00 -START. 

DISPLAY "INPUT USER ID:". 
ACCEPT USERID. 
DISPLAY " INPUT PASSWORD:". 
ACCEPT PASSWD. 

DISPLAY " INPUT ACCOUNT NUMBER: " . 
ACCEPT ACCNT. 
STRING USERID 
MUL ( 1 ) 

PASSWD 
NUL(l) 
ACCNT 

NUL(l) DELIMITED BY SIZE 
INTO I DENT. 

***************************************************************** 

* * 

* GET REMOTE NODE NAME AND FORM ASCIZ STRING. * 

* * 
***************************************************************** 

DISPLAY " ENTER REMOTE NODE NAME:". 
ACCEPT TEMP-NODE. 
STRING TEMP-NODE 

NUL(l) DELIMITED BY SIZE 

INTO NODE-NAME. 

***************************************************************** 

* * 

* GET REMOTE INPUT AND OUTPUT FILE NAMES AND FORM * 

* ASCIZ STRING FOR EACH FILE. * 

* * 
***************************************************************** 

DISPLAY " INPUT FILE SPEC. FOR INPUT FILE:". 
ACCEPT TEMP- INPUT. 
STRING TEMP- INPUT 

NUL(l) DELIMITED BY SIZE 

INTO REMOTE- INPUT. 
DISPLAY " INPUT FILE SPEC. FOR OUTPUT FILE:". 
ACCEPT TEMP-OUTPUT. 
STRING TEMP-OUTPUT 

NUL(l) DELIMITED BY SIZE 

INTO REMOTE-OUTPUT. 
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**********************************.******************************* 

* * 

* ACCESS THE NETWORK. IF THE CALL DOES NOT COMPLETE * 

* SUCCESSFULLY, DISPLAY AN ERROR MESSAGE AND EXIT. * 

* * 
*********************************************** 

CALL "OPNNTW" USING 

OPNLUN 

IOST 

MSTAT 

COUNT 1 . 
IF IOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

MOVE IOSTAT (1) TO MSG 1- STAT 1 
MOVE IOSTAT (2) TO MSG1-STAT2 
DISPLAY MSG1 
GO E100-END. 

***************************************************************** 

* * 

* OPEN REMOTE FILE FOR INPUT. IF THERE IS AN OPEN * 

* ERROR, PRINT AN ERROR MESSAGE AND EXIT. * 

* * 
***************************************************************** 

CALL "OPRNFW" USING 
INPLUN 
IOST 

NODE-NAME 
I DENT 

REMOTE- INPUT 
I CHAR 
LENGTH 1 
BLOCK1 . 
IF IOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

MOVE IOSTAT (1) TO MSG 2- STAT 1 
MOVE IOSTAT (2) TO MSG 2 -STAT 2 
DISPLAY MSG2 
GO El 00 -END. 

***************************************************************** 

* * 

* OPEN REMOTE FILE FOR OUTPUT. IF THERE IS AND OPEN * 

* ERROR, DISPLAY AN ERROR MESSAGE AND EXIT. * 

* * 
***************************************************************** 

CALL "OPWNFW USING 
OUTLUN 
IOST 

NODE -NAME 
I DENT 

REMOTE-OUTPUT 
I CHAR 
I CHAR 
LENGTH 1 
BLOCK1 . 
IF IOSTAT (1) = 1 

NEXT SENTENCE 

ELSE 

MOVE IOSTAT (1) TO MSG 3- STAT 1 
MOVE IOSTAT ( 2 ) TO MSG3-STAT2 
DISPLAY MSG 3 
GO Dl 00 -CLOSE. 

(continued on next page) 
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************************************************** 

* * 

* TRANSFER RECORDS BETWEEN THE REMOTE FILES. WHEN * 

* THE END-OF-FILE IS ENCOUNTERED, EXIT FROM THE LOOP. * 

* EXIT FROM THE LOOP IF A READ OR WRITE ERROR OCCURS * 

* AND BRANCH TO THE APPROPRIATE ROUTINE TO DISPLAY AN * 

* ERROR MESSAGE. * 

* * 
***************************************************************** 

PERFORM LOOP VARYING I FROM 1 BY 1 UNTIL I = 100. 

LOOP. 

CALL "GETNFW" USING 
INPLUN 
IOST 

I ARRAY- SIZE 
I ARRAY. 

IF IOSTAT (1) NOT = 1 AND IOSTAT (2) NOT = EOF 

GO B100-READERR. 
MOVE IOSTAT (2) TO LENGTH 1 . 

IF IOSTAT (1) NOT = 1 AND IOSTAT (2) = EOF 
MOVE TTRUE TO EOFFG 

ELSE 

MOVE FFALSE TO EOFFG. 
IF EOFFG = TTRUE GO D100-CLOSE. 
CALL "PUTNFW" USING 

OUTLUN 

IOST 

LENGTH 1 

I ARRAY 

IF IOSTAT (1) NOT = 1 AND IOSTAT (2) NOT = EOF 
GO C100-WRITERR. 

***************************************************************** 

* * 

* A READ ERROR OCCURRED DURING FILE TRANSFER. PRINT * 

* AN ERROR MESSAGE AND EXIT. * 

* * 
***************************************************************** 

B 1 - RE ADERR . 

MOVE IOSTAT (1) TO MSG4-STAT1 . 
MOVE IOSTAT (2) TO MSG4-STAT2. 
DISPLAY MSG4. 
GO D100-CLOSE. 

***************************************************************** 

* * 

* A WRITE ERROR OCCURRED DURING FILE TRANSFER. PRINT * 

* AN ERROR MESSAGE AND EXIT. * 

* * 
***************************************************************** 

C100-WRITERR. 

MOVE IOSTAT (1) TO MSG5-STAT1. 

MOVE IOSTAT (2) TO MSG5-STAT2. 
DISPLAY MSG5. 
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*********************************************************** 

* * 

* CLOSE BOTH REMOTE FILES. * 

* * 
***************************************************************** 

D100-CLOSE. 

PERFORM LOOP1 VARYING I FROM INPLUN 3Y I UNTIL I = OUTLUN. 

LOOP1 . 

CALL "CLSNFW" USING 
I 

IOST. 

***************************************************************** 

* * 

* IF AN ERROR OCCURRED BEFORE ENCOUNTERING THE * 

* SND-OF-FI LE , EXIT. OTHERWISE THE TRANSFER WAS * 

* SUCCESSFUL, SO DISPLAY A SUCCESS MESSAGE AND 

* EXIT. * 

<r " 
***************************************************** 

END-LOOP1 . 

IF EOFFG NOT = TTRUE 
GO El 00 -END 

ELSE 

DISPLAY "END OF FILE REACHED. FILES CLOSED.". 

E100-END. 

STOP RUN. 
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3.8.23 BASIC-PLUS-2 Remote File Access Programming Example 
(Append) 



The program BASAPP appends the contents of a local ASCII file to the end of a 
remote ASCII file and then closes both files. If an error occurs, the program displays 
an error message. In the following example, the user ID, the password, and the 
account number are entered from the terminal. 

NOTE 

This programming example is also included in your tape or disk kit. 



5 !!! To task build you must edit the task build command !!! & 



file and the ODL file created by the build. !!! & 

>Add the lines ! ! ! & 

! ! ! & 

ACTFIL=4 ! ! ! & 

EXTSCT=$$FSR1:2700 ! ! ! & 

to the task build command file. !!! & 

! ! ! S. 

>Append ! ! ! & 

! ! < & 

-NETL I B-NETLB2 ! ! ! & 

to the USER: line of the ODL file. !!! & 

! ! ! & 

>Add the lines ! ! ! & 

! ! ! & 

NETLIB: . FCTR LB: [ 1 , 1 ]NETFOR/LB !•! & 

NETLB2: .FCTR LB: [l,l]NETFOR/LB:NFAFSR ! ! ! St 

to the ODL file. ! ! ! & 



ON ERROR GO TO 145 ! ERROR HANDLER 



10 ! ! ! DEFINE ARRAY CONTSTANTS ! ! ! S. 

\ DIM ISTAT% ( 1% ) , JSTAT% ( 1% ) ,KSTAT% ( 1% ) , LSTAT% ( 1% ) ,MSTAT% ( 2% ) St 

\ DIM NSTAT%(1%) ! DEFINE ARRAY ELEMENTS S> 

\ NULL$=STRING$(1%,0%) ! DEFINE NULL CHAR FOR ASCIZ 

15 ! ! ! DEFINE CONSTANTS ! ! ! & 

0PNLUN%=2% ! NETWORK OPEN LUN & 

\ APPLUN%=1% ! FILE LUN & 

\ C0UNT%=1% !MAX # OF LOGICAL LINKS St 

\ FLAG%=0% ! END OF FILE FLAG & 

\ ICHAR$="AVF" ! MODE , TYPE, CARRIAGE CONTROL 

20 INPUT "ENTER REMOTE NODE NAME (MAX. 6 CHARACTERS ) " ; NODNAM$ St 

\ IF LEN(NODNAM$)>6% THEN PRINT & 

"NAME TOO LONG, PLEASE RE-ENTER" St 
\ PRINT \ GO TO 20 

30 PRINT "NODE NAME = " ; NODNAM$ \ NODNAM$ =NODNAM$ +NULL $ & 

! CREATE ASCIZ STRING FOR OPANFW 

40 PRINT " ENTER FILE SPEC. OF REMOTE FILE FOR APPEND:" & 

\ INPUT BUF1$ \ BUF1$=BUF1$+NULL$ & 

\ PRINT "ENTER FILE SPEC. OF LOCAL FILE TO BE APPENDED:" S> 

\ INPUT BUF2$ 
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! ! ! GET 


INFORMATION NECESSARY TO ACCESS FILES IN THE ! ! ! 


Si 




! ! ! REMOTE NODE FOR OPANFW ! ! ! 


S. 


\ 


INPUT 


"ENTER USER ID: " ;USERID$ !GET USER ID 


St 


\ 


INPUT 


"ENTER PASSWORD :"; PASSWD$ ! GET PASSWORD 


Si 


\ 


INPUT 


"ENTER ACCOUNT NUMBER: " ;ACCNT$ ! GET ACCOUNT NUMBER 


Si 


\ 


IDENT$= ! 


USERID$+NULL$+PASSWD$+NULL$+ACCNT$+NULL$ 


Si 


\ 




! CREATE ASCIZ STRING FOR OPANFW 




60 


!!! CREATE NETWORK MAILBOX FOR ONLY ONE LINK !!! 


& 


\ 


CALL 


OPNNTW BY REF ( OPNLUN% , LSTAT% ( ) , MSTAT% ( ) , COUNT% ) 


St 


\ 


IF 


LSTAT%(0%)=1% THEN 70 ! IF OPEN NETWORK SUCCESSFUL, 


St 






lOPEN REMOTE AND LOCAL FILES. 


Si 




ELSE . 


PRINT "MAIL30X CREATION ERROR" !IF UNSUCCESSFUL, PRINT 


& 


\ 




PRINT " STATUS = "j LSTAT% ( 0% );","; LSTAT% ( 1% ) 


St 


\ 




GO TO 150 ! MESSAGE AND STATUS AND EXIT 




/ U 


! ! ! OPEN LOCAL FILE ! ! ! 


r 
at 


\ 


OPEN 


BUF2$ FOR INPUT AS FILE #4 




QA 


! ! ! OPEN REMOTE FILE FOR APPEND ! ! ! 


& 


\ 


CALL 


OPANFW BY REF ( APPLUN% , I STAT% ( ) , NODNAM$ , I DENT$ , BUF1 $ , 


St 






ICHAR$ , LENGTH% , IBLOCK% ) 


Si 


\ 


IF 


ISTAT%(0%)=1% THEN 100 ! IF SUCCESS, APPEND TO REMOTE 


St 






•FILE FROM LOCAL FILE 


Si 




ELSE 


PRINT "CAN NOT OPEN REMOTE FILE." IIP ERROR ON OPEN, 


Si 


\ 




PRINT "STATUS = " ; ISTAT%( 0%) ; " , " ; ISTAT%( 1% ) 


St 


\ 




GO TO 120 '.OUTPUT MESSAGE AND STATUS AND 


Si 






!EXIT 




100 


! ! ! 


READ RECORDS FROM LOCAL FILE AND WRITE THEM TO ! ! ! 


St 


\ 


! ! ! 


REMOTE FILE. ! ! ! 


St 


\ 


FLAG% = 


1% !SET FLAG FOR END OF FILE CHECK 


St 




INPUT 


#4,TEMP$ ! READ FROM LOCAL FILE 


Si 


\ 


CALL 


PUTNFW BY REF ( APPLUN% , JSTAT% ( ) , LEN ( TEMP$ ) , TEMP$ ) 


St 






! APPEND TO REMOTE FILE 


St 


\ 


IF 


JSTAT%(0%)=1% THEN 100 ! IF SUCCESSFUL, READ NEXT RECORD& 




ELSE 


PRINT "WRITE ERROR FROM REMOTE FILE." ! IF ERROR, PRINT 


Si 






PRINT "STATUS = " ; JSTAT% ( 0%) ; " , " ; JSTAT%( 1% ) 


Si 


\ 




GO TO 150 ! MESSAGE AND STATUS AND EXIT 




X X u 


i i ; eof FOUND CLOSE BOTH FILES AND NETWORK ! ! ! 


c. 


\ 


FLAG% = 


0% ! CLEAR END OF FILE FLAG 


Si 


\ 


CLOSE 


#4 ! CLOSE LOCAL FILE 


& 


\ 


CALL 


CLSNFW BY REF ( APPLUN% , KSTAT% ( ) ) ! CLOSE REMOTE FILE 


Si 


\ 


IF 


KSTAT%(0%)=1% THEN 120 IIP SUCCESS DEACCESS NETWORK 


St 




ELSE 


PRINT " CAN NOT CLOSE REMOTE FILE." ! IF CLOSE ERROR, 


S. 


\ 




PRINT "STATUS = " ;KSTAT% ( 0% ) ; " , " ;KSTAT% ( 1% ) 


Si 


\ 




GO TO 150 ! PRINT MESSAGE, STATUS AND EXIT 




120 


CALL 


CLSNT BY REF ( NSTAT% ( ) ) ! DEACCESS NETWORK 


Si 


\ 


IF 


NSTAT%(0%)=1% THEN 140 ! IF SUCCESS, APPEND COMPLETE 


St 




ELSE 


PRINT "CAN NOT CLOSE NETWORK." ! IF ERROR, PRINT 


Si 


\ 




PRINT "STATUS = "; NSTAT% ( 0% );","; NSTAT$ ( 1% ) 


St 


\ 




GO TO 150 ! MESSAGE AND STATUS AND EXIT 
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140 


PRINT 


" APPEND COMPLETE. END 


PROGRAM EXECUTION" 




\ 


GO TO 


150 






145 


IF 


ERR <> 11 THEN 146 


!IF NOT EOF, PRINT ERROR 






ELSE 


IF FLAG%=0% THEN 146 


! I F EOF AND EOF FLAG NOT 


SET , 








! PRINT ERROR 






ELSE 


RESUME 110 


!EOF SO CLOSE BOTH FILES 




146 


PRINT 


"ERROR " ; ERR ; " AT LINE 


" ; ERL ! PRINT ERROR AND LINE 


NO. 


150 


END 
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3.8.24 BASIC-PLUS-2 Remote File Access Programming Example 
(Read/Write) 

The program BASRRW reads the contents of one remote file into another remote file. 
When an end-of-file is encountered, the last record is written to the remote file and 
both files are closed. 

NOTE 

This programming example is also included in your tape or disk kit. 
10 !!! To task build you must edit the task build command !!! & 



!!! file and the ODL file created by the build. !•! & 

! • ! >Add the lines ! ! ! & 

! ! ! ! ! ! & 

! ! ! ACTFIL*4 ' ! ! 6 

! 1 ! EXTSCT»$$FSR1: 10000 ! ! ! & 

!!! to the task build command file. !!! & 

!!! !!! & 

! ! ! >Append ! ! ! & 

! ! ! ! ! ! & 

! ! ! -NETL I B-NETLB2 • ! ! & 

!!! to the USER: line of the ODL file. !!! & 

!!! !!! 6 

! ! ! >Add the lines !!! 6 

III III St 

III NETLIB: . FCTR LB : [ 1 , 1 ] NETFOR/LB !!! & 

! ! ! NETLB2 : . FCTR LB : [ 1 , 1 ] NETFOR/LB : NFAFSR ! ! ! 6 

! ! ! to the ODL file. ! ! ! £> 



20 


! ! ! DEFINE ARRAY CONSTANTS ! ! ! 




& 




DIM IARRAY%(255%) ,ISTAT%(1%) ,MSTAT%(2%) 


6 








! DEFINE MAXIMUM STRING LENGTHS 


& 


\ 


NULL$=STRING$ ( 1% , 0% ) 




'DEFINE MAXIMUM STRING LENGTHS 


& 


30 


i i i DEFINE CONSTANTS ! ! ! 






£ 




ICHARS$="AVF" 




•MODE, TYPE, CARRIAGE CONTROL 


& 


\ 


OPNLUN%»7% 




! NETWORK OPEN LUN 


& 


\ 


COUNT%«2% 




•MAX. # OF ACTIVE LOGICAL LINKS 


& 


\ 


INPLUN%=1% 




!LUN ASSIGNED TO INPUT FILE 


Sl 


\ 


OUTLUN%=2% 




!LUN ASSIGNED TO OUTPUT FILE 


& 


\ 


EOF%=20519% 




SEND OF FILE STATUS RETURN 


& 


\ 


FALSE%=0% 




'FLAG INDICATING FALSE 


& 


\ 


TRUE%=-1% 




! FLAG INDICATING TRUE 




40 


! ! ! INPUT NODE NAME ! ! ! 






& 




INPUT "ENTER REMOTE NODE NAME 


(MAX. 6 CHARACTERS) :";NODNAM$ 


& 


\ 


IF LEN(NODNAM$)>6% 


THEN PRINT 


& 




"NAME TOO LONG, 


PLEASE 


RE-ENTER" 


& 


\ 


PRINT \ GO TO 40 






& 




ELSE NODNAM$ =NODNAM$ +NULL$ 


! CREATE ASCIZ STRING 




50 


!!! GET INFORMATION NECESSARY TO ACCESS FILES IN THE •■! 


& 




! ! ! REMOTE NODE. 




! ! ! 


& 


\ 


INPUT "ENTER USER ID:" 


;USERID$!GET USER ID 


& 


\ 


INPUT "ENTER PASSWORD: 


" ; PASSWD$ ! GET PASSWORD 


& 


\ 


INPUT "ENTER ACCOUNT NUMBER:" 


;ACCNT$!GET ACCOUNT NUMBER 


& 


\ 


IDINFO$=USERID$+NULL$+PASSWD$+NULL$+ACCNT$+NULL$ 


s. 


\ 






! CREATE ASCIZ STRING 
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60 !!! INPUT FILE SPECIFICATION FOR INPUT & OUTPUT FILES !!! & 

INPUT "INPUT FILE SPEC. FOR INPUT FILE" ; INFIL$ & 

\ INFIL$=INFIL$+NULL$ ! APPEND NULL CHARACTER & 

\ INPUT "INPUT FILE SPEC. FOR OUTPUT FILE" ;OUTFIL$ & 

\ OUTFIL$=OUTFIL$+NULL$ ! APPEND NULL CHARACTER 



7 ! ! ! DECLARE NETWORK TASK ! ! ! & 

CALL OPNNTW BY REF ( OPNLUN% , I STAT% ( ) , MSTAT% ( ) , COUNT% ) & 

! ACCESS NETWORK & 

\ LOCl»l ! ORIGIN OP CALL FOR SUBROUTINE & 

\ GOSUB 150 ! CHECK STATUS 



80 !!! OPEN FILE FOR INPUT. THE FILE RESIDES ON A REMOTE NODE !!! & 

CALL OPRNFW BY REF( INPLUN%, ISTAT% ( ) ,NODNAM$ , IDINFO$ , INFIL$ , S. 

I CHARS $ , LNTH% , BLOCK% ) !OPEN REMOTE FILE FOR INPUT & 

\ LOCl=2 'ORIGIN OF CALL FOR SUBROUTINE & 

\ GOSUB 150 ! CHECK STATUS 



90 ! ! ! OPEN FILE FOR OUTPUT. FILE RESIDES ON A REMOTE NODE ! ! ! & 

CALL OPWNFW BY REF(OUTLUN%, ISTAT% ( ) ,NODNAM$ , IDINFO$ , OUTFIL$ , S. 

ICHARS$,LNTH%,BLOCK%) !OPEN REMOTE FILE FOR OUTPUT & 

\ LOCl=3 "ORIGIN OF CALL FOR SUBROUTINE & 

\ GOSUB 150 'CHECK STATUS 



100 

102 
104 



106 

107 
108 
110 

\ 
120 

130 

\ 
\ 
\ 



ONCE THE FILES ARE SUCCESSFULLY OPENED, WE MAY 
TRANSFER RECORDS. THE FILE ASSOCIATED WITH LUN 1 
IS OPENED FOR READING, THE FILE ON LUN 2 IS OPENED 
FOR WRITING. 
FOR I%=1% TO 100% 



CALL 



GETNFW BY REF( INPLUN% , ISTAT% ( ) , 256% , I ARRAY% ( ) ) 
IREAD A RECORD FROM INPUT FILE 



IF ISTAT%(0%)<>1% AND ISTAT% ( 1% ) <>EOF% THEN 110 & 

!IF UNSUCCESSFUL, PRINT MESSAGE & 
ELSE LNTH%=ISTAT%(1%) 'SAVE NO. OF BYTES TRANSFERRED 



105 ! ! ! CHECK FOR END OF FILE ! ! • & 

IF ISTAT%(0%)<>1% AND ISTAT%(l%)=EOF% THEN EOFFG%=TRUE% & 
ELSE EOFFG%=FALSE% !SET FLAG IF END OF FILE 



NEXT 1% 



IF EOFFG% =TRUE% THEN 130! IF END OF FILE, CLOSE FILES S> 
ELSE CALL PUTNFW BY REF ( OUTLUN% , I STAT% ( ) , LNTH% & 
, IARRAY%( ) ) ! WRITE RECORD 

IF ISTAT%(0%)<>1% AND ISTAT( 1% ) <>EOF% GO TO 120 & 
ELSE A%=1% !IF UNSUCCESSFUL, PRINT MESSAGE 

•TERMINATE LOOP 



' ! ! READ ERROR OCCURRED ! ! ! 
PRINT "READ ERROR. STATUS 
GO TO 130 



; ISTAT% ( 0% ) ; " , " ; ISTAT% ( 1% ) 
! CLOSE BOTH FILES 



! ! ! WRITE ERROR OCCURRED ! ! ! 

PRINT "WRITE ERROR. STATUS = "; ISTAT% ( 0% );","; ISTAT% ( 1% ) 
! ! ! CLOSE FILES ! ! ! 



FOR 



NEXT 
IF 



ELSE 



J%=1% TO 2% ! CLOSE FILES 1 AND 2 

CALL CLSNFW(J%,ISTAT%() ) ! CLOSE EACH FILE 
J% 'TERMINATE LOOP 

EOFFG% < >TRUE% THEN 140 ! IF FLAG NOT TRUE, TRANSFER NOT 

! SUCCESSFUL 
PRINT "END OF FILE REACHED. FILE CLOSED" 

! INDICATE TRANSFER SUCCESSFUL 
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140 GOTO 170 ! BRANCH TO END 

150 ! ! ! SUBROUTINE TO CHECK STATUS ON COMPLETION OF OPEN CALLS ! ! ! & 

IF ISTAT%(0%)=1% THEN 160 ! IF SUCCESS, JUST RETURN & 

ELSE PRINT "OPEN ERROR. STATUS = " ; ISTAT% ( 0% ) ; " , " ; ISTAT7% ( 1% ) & 

\ PRINT "LOC = ";LOCl SORIGIN OF CALL S. 

\ GO TO 170 ! QUIT IF UNSUCCESSFUL 

160 RETURN !EXIT FROM SUBROUTINE 

170 END 'END EXECUTION 
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3.9 FORTRAN Task Control 



This section contains descriptions and usage guidelines for the FORTRAN task con- 
trol calls summarized in Table 3-4. Task control allows you to run or abort specific 
tasks according to time schedules that you define in a DECnet call. 



Table 3-4: FORTRAN Task Control Call Summary 
Call Function 

ABONCW Abort an executing task or cancel a scheduled task 

BACUSR Build accounting information and the user ID portion of the connect 

block 

RUNNCW Execute an installed task in a remote node 

Before you issue any of these calls you must access the network by issuing an 
OPNNTW call. When you complete task control operations, you must issue the 
CLSNTW call to deaccess the network. 

3.9.1 Waiting for Requests 

All calls are synchronous and pass control back to the user task only after the opera- 
tion completes. 

3.9.2 RSX Remote Task Control Utility 

In order for these calls to execute successfully, the RSX Remote Task Control utility 
(TCL) must be installed on the remote node. If TCL is not installed, the call will 
complete with an error. 
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ABONCW 



Abort an Executing 

Task or Cancel 
a Scheduled Task 



3.9.3 ABONCW - Abort an Executing Task or Cancel a Scheduled 
Task 

Use: 

Call ABONCW to abort an executing task or cancel a scheduled task. 
Format: 

CALL ABONCW (lun, [status], ndsz,indnm,passwdsiz, 
passwd, tsksiz, tsknam,[ident] , [mask]) 

Arguments: 

lun 

specifies an integer variable or constant and must be a logical unit number not 
currently in use. 

* status 

specifies an integer array containing the following completion status information 
on return from ABONCW: 

status(l) Returns an error/completion code 

status(2) If the error code in status(l) indicates a network reject (-7), status 
(2) will contain the disconnect or reject reason code. Refer to 
Appendix A. Otherwise, status{2) will contain a directive error 
code (if status(l) is -40) or null value (0). 

ndsz 

specifies an integer variable or constant containing the node name length in 
bytes. 

ndnm 

specifies a 1- to 6-element byte array containing the name of the node to which 
this abort request is directed. 

passwdsiz 

specifies an integer variable or constant containing the password length in bytes. 
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passwd 

specifies a 1- to 8. -element byte array containing the user password (the password 
you use to log on to the remote system) for the node you want to access. 

A privileged password allows a user to abort any task running on the remote node 
without specifying the ident parameter. A nonprivileged password allows a user to 
abort a task if the correct ident parameter is specified. 

tsksiz 

specifies the remote task name length in bytes. 

tsknam 

specifies a 1- to 6-element byte array containing the name of the remote task you 
want to abort or cancel. 

* ident 

specifies an integer variable containing the negated task control block address of 
the remote task. This value is returned to the ident parameter of the RUNNCW 
call when the RUNNCW call completes. This argument is optional for a user with 
a privileged password. 

* mask 

indicates the way ABONCW is used. This is an optional argument. If you omit 
this argument or if its value equals 0, only the executing task you specified in the 
call is aborted. 

If the value equals 1, the rescheduling of the specified task is cancelled and the 
presently active task continues to execute. 

If the value is greater than 1, the executing task is aborted and rescheduling of the 
task is cancelled. 
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Error/Completion Codes: 

1 The call completed successfully. 

-1 System resources needed for the logical link are not available. 

-7 The connection was rejected by the network. Refer to Appendix A. 

-8 A logical link has already been established using this LUN. 

-9 The task is not a network task: OPNNT did not execute successfully. 
-21 The requested task is not installed on the remote node. 
-23 An ABONCW was issued for a task that was not active. 

-24 A privileged violation has occurred. You are not a privileged user, and you are attempt- 
ing an ABONCW for a task with improper identification. 

-25 An ABONCW was issued for a task that either was being loaded into or was exiting from 
the remote node. 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-11M/M-PLUS Executive Reference Manual. 
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BACUSR 



Build Account and User 
ID Information Area 



3.9.4 BACUSR - Build Account and User ID Information Area 

Use: 

Call BACUSR in the task requesting the connection if access control information 
(user ID and account) is not passed to the remote node in an alias node name 
specification. BACUSR allows you to build the account and user ID areas of the 
connect block for task control programming. 

BACUSR is similar in function to BACC. Unlike BACC, however, BACUSR does 
not allow you to specify a password. The password is specified in a task control 
program as a parameter of a call (ABONCW or RUNNCW). 

Format: 

CALL BACUSR ([status],[usersz,user],[accnosz,accno]) 
Arguments: 

* status 

specifies an integer variable. On return from BACUSR, this optional argument is 
set to .TRUE.(-l) if the call completed successfully, or it is set to .FALSE. (0) if 
one of the arguments to BACUSR is invalid. 

usersz 

specifies an integer variable or constant containing the user ID length in bytes. 
user 

specifies a 1- to 16.-byte array containing the user ID. Usersz and user are paired 
optional arguments. Include both or omit both. 

accnosz 

specifies an integer variable or constant containing the length in bytes of the 
account number (not used for RSX target systems). 

accno 

specifies a 1- to 16. -byte array containing the account number. Accnosz and accno 
are paired optional arguments. Include both or omit both. 
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RUNNCW 



Execute an Installed 
Task in a Remote Node 



3.9.5 RUNNCW - Execute an Installed Task in a Remote Node 
Use: 

RUNNCW allows you to execute an installed task in a remote node using any or 
all of the following options: 

• Execute the task immediately 

• Schedule the task for execution at some future time 

• Schedule the task for periodical execution based on predefined time schedules 
Format: 

CALL RUNNCW (lun,[status],ndnm,passwdsz,passwd, 
tsksz, tsknam, [ident] , [uic] , [smg, snt] , 
[rmg,rnt]) 

Arguments: 

lun 

specifies an integer variable or constant and must be a logical unit number not 
currently in use. 

* status 

specifies an integer array containing the following completion status information 
on return from RUNNCW: 

status(l) Returns an error/completion code 

status{2) If the error code in status(l) indicates a network reject (-7), status 
(2) will contain the disconnect or reject reason code. Refer to 
Appendix A. Otherwise, status(2) will contain a directive error or 
will not be used. 

ndsz 

specifies an integer variable or constant containing the node name length in 
bytes. 

ndnm 

specifies a 1- to 6-element byte array containing the name of the node to which 
this request is directed. 
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passwdsiz 

specifies an integer variable or constant containing the password length in bytes. 
passwd 

specifies a 1- to 8. -element byte array containing the user password (the password 
you use to log on to the remote system) for the node you want to access. 

A privileged password allows you to run a task under any user identification code 
on the remote node. A nonprivileged password allows you to run a task only under 
the UIC assigned to you. 

tsksiz 

specifies an integer variable or constant containing the remote task name length 
in bytes. 

tskname 

specifies a 1- to 6-element byte array containing the name of the remote task you 
want to execute. 

ident 

specifies an integer variable containing the negated task control block address of 
the remote task when RUNNCW completes. This value will be used in 
ABONCW. If you do not plan to cancel or abort this task later on, you do not need 
to include this argument. 

uic 

specifies a 2-byte array containing the group and user codes under which the task 
will run on the remote node. The first element of the array contains the user 
member code; the second element contains the user group code. This argument is 
optional with a privileged password. If a privileged user omits this argument, the 
task will run under its default UIC on the remote node. 

smg 

specifies an integer variable or constant containing the schedule delta magnitude. 
The value of this optional argument is the difference in time from the issuance of 
the call to the time the task is to be run at the remote node. 

This argument is used with the following argument, snt, which specifies the unit 
of time used to schedule the task (in hours, minutes, seconds, or ticks). In no case 
can the magnitude exceed 24 hours. 
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snt 

specifies an integer variable or constant containing the schedule delta unit. This 
argument is a code identifying the time unit specified with the smg argument. 
Time unit codes and their meanings are: 

Code Description 

1 Ticks: A tick occurs for each clock interrupt and depends on the type of clock 
installed in the system. 

Line frequency clock: The tick rate is either 50 or 60 per second and corresponds 
to the power line frequency. 

Programmable clock: A maximum of 1000 ticks per second is available. The exact 
rate is determined at system generation. 

2 Seconds 

3 Minutes 

4 Hours 
rmg 

specifies an integer variable or constant containing the reschedule delta magni- 
tude. The reschedule interval is the difference in time from task initiation to the 
time the task is to be reinitiated on the remote node. The task is executed each 
time the elapsed time equals the reschedule magnitude specified in this argu- 
ment. If this time interval elapses and the task is still active, no reinitiation 
request is issued. However, a new reschedule interval is started. 

This argument is used with the following argument, rnt, which specifies the unit 
of time used to reschedule the task (in hours, minutes, seconds, or ticks). In no 
case can the magnitude exceed 24 hours. 

rnt 

specifies an integer variable or constant containing the reschedule delta unit. This 
argument is a code identifying the time unit to be used with the delta magnitude 
specified in the rmg argument. 
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NOTE 



• If you omit the smg, snt, rmg, and rnt arguments, the task is exe- 
cuted immediately. 

• If you specify smg and snt, but omit rmg and rnt, the task is exe- 
cuted once at the scheduled time. 

• If you specify rmg and rnt, but omit smg and snt, the task is exe- 
cuted immediately and again each time the reschedule delta time 
has elapsed. 

• You can specify all four arguments. For example: 

CALL RUNNC W ( lun, status, ndsz, tsksiz, tsknam, 
i«c, 1,4,4,4) 

specifies that you want the task to run for the first time in one hour 
and then run every four hours after that. 

Error/Completion Codes: 

1 The call completed successfully. 

-1 System resources needed for the logical link are not available. 

-7 The connection was rejected by the network. Refer to Appendix A. 

-8 A logical link has already been established using this LUN. 

-9 The task is not a network task: OPNNT did not execute successfully. 
-20 There is insufficient dynamic memory on the remote node. 
-21 The requested task is not installed on the remote node. 
-22 RUNNC W has an invalid time parameter. 

-23 An RUNNCW call was issued without scheduling parameters for a task that is already 
active. 

-24 A privileged violation has occurred. You are not a privileged user, and you are attempt- 
ing to issue a RUNNCW under a UIC that is different from the UIC to which you are 
assigned on the remote node. 

-26 A RUNNCW was issued under an invalid UIC (for example, [1,0] or [0,1]). 

-40 A directive error has occurred. Directive error codes are defined in the 
RSX-11M/M-PLUS Executive Reference Manual. 
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3.9.6 FORTRAN Task Control Programming Example 



The program RUNABO.FTN uses DECnet task control calls to run or abort a task on 
a specified local or remote node. After your task control request has been executed, 
you will be prompted to enter another request to run or abort the associated task. 
When you have finished entering the task control requests, press (ctrl/z) to exit from 
the request-prompting loop and stop the program. 

Before running RUNABO.FTN, the TCL task must be installed on the target node as 
shown at the beginning of the program. 

NOTE 

This programming example is also included in your tape or disk kit. 

c 

C RUNABO.FTN 



C 

C - USES THE DECNET TASK CONTROL CALLS TO RUN OR ABORT A 

C TASK ON THE SPECIFIED NODE (LOCAL OR REMOTE). 

C - TASK "TCL" MUST BE INSTALLED AT THE TARGET NODE.S 

C - SAMPLE COMMANDS TO DEVELOP THIS TASK FOLLOW 

C 

C >FOR RUNABO , RUNABO=RUNABO 

C >TKB RUNABO, RUl<ABO= RUNABO , [1,1] NETFOR/LB 

C > I NS RUNABO/TASK= . . . CTL 

C 



LOGICAL*l ANSWER , RUN , ABO , T ARTSK ( 6 ) , TARNOD ( 6 ) ,PASSWD(8) ,USERID(16) 
LOGICAL*l ACCNT(16) 
INTEGER STATUS ( 2 ) , STAT 
INTEGER* 2 MSTAT ( 3 ) 
DATA RUN/'R'AABO/'AV 

C 

C CREATE NETWORK DATA QUEUE 
C 

CALL OPNNTWd, STATUS, MSTAT) 

IF (STATUS(l) .NE. 1) WRITE( 5 , 8 ) STATUS ( 1 ) 

C 

C PROMPT FOR TARGET NODE, AND TARGET TASK. 

C 

10 WRITE(5,1) 

1 FORMAT ( 5X , $ ' TARGET NODE ? : • ) 
READ ( 5 , 2 , END= 9 9 9 ) ICNT 1 , TARNOD 

2 FORMAT ( Q , 16A1 ) 

C 

WRITE(5,3) 

3 FORMAT (5X,$' TARGET TASK ? :') 
READ (5 , 2 , END=999 ) ICNT2 , TARTSK 

C 

C PROMPT FOR ACCESS CONTROL INFORMATION 
C 

WRITE(5,50) 
50 FORMAT (5X,$' TARGET USER I.D. ?:*) 
READ (5,2,END=999)ICNT4,USERID 

C 

WRITE(5,4) 

4 FORMAT ( 5X , $ ' TARGET PASSWORD ? : ' ) 
READ (5,2,END=999)ICNT3,PASSWD 



(continued on next page) 
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WRITE(5,11) 

1 1 FORMAT ( 5X , $ ' TARGET ACCOUNT NUMBER ? : ' ) 
READ (5,2, END=999 ) ICNT5 , ACCNT 

C 

WRITE(5,6) 

6 FORMAT ( 5X , $ ' RUN (R) OR ABORT (A) ? :') 
READ (5,7, END= 999) ANSWER 

7 FORMAT (Al) 

C 

C DECIDE WHETHER TO CALL BACUSR 
C 

IF (ICNT4 . EQ. .AND. ICNT5 .EQ. 0) GO TO 70 
CALL BACUSR (STAT, ICNT4 ,USERID, ICNT5, ACCNT) 
IF (STAT .EQ. .TRUE.) GO TO 70 
WRITE (5,80) STAT 
80 FORMAT (* ERROR BUILDING CONNECT BLOCK ' ) 
GOTO 10 



C DECIDE WHETHER TO RUN OR ABORT THE TASK. 
C 

70 IF (ANSWER .EQ. ABO) GOTO 20 
IF (ANSWER .EQ. RUN) GOTO 30 
GOTO 999 

C 

C ABORT THE TASK, AND PRINT STATUS. 
20 WRITE (5,100) 
100 FORMAT (5X,$'IF A PRIVILEGED PASSWORD IS USED, ENTER 0. IDENT ?:') 

READ (5,110) IDENT 
110 FORMAT (16) 

CALL ABONCW (2, STATUS, ICNT1 , TARNOD, ICNT3 ,PASSWD, ICNT2 , TARTSK, IDENT) 

C 

WR I TE ( 5 , 8 ) STATUS ( 1 ) 
8 FORMATC STATUS ■ ',17) 
GOTO 10 

C 

C RUN THE TASK, AND PRINT STATUS. 
C 

30 CALL RUNNCW( 2, STATUS, ICNT1, TARNOD, ICNT3 , PASSWD, ICNT2 , TARTSK, IDENT) 
WRITE (5,8)STATUS(1) 

IF (STATUS(l) .EQ. 1) WRITE (5,90) IDENT 
90 FORMAT (* THE IDENT IS ',16) 
GOTO 10 
999 STOP 
END 
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DLX: Direct Line Access Controller 



DLX allows programs to send and receive data that bypasses the standard DECnet 
user interface. This permits: 

• Communication with non-DECnet based systems 

• Reduction of overhead messages exchanged with other systems or systems that may 
be running DLX 

To use DLX, you issue queued input/output (QIO) calls to the NX: device. The DLX 
interface can be used to communicate over all devices supported by DECnet-RSX. 

DLX is automatically built for RSX-11M-PLUS systems. It is optional for 
RSX-11M/RSX-11S systems. However, DLX is required for down-line loads and up- 
line dumps from RSX-11S systems. 

DLX programming requires a thorough knowledge of MACRO-11 assembly language 
and experience in writing real-time application programs. You must write tasks that 
synchronize with each other before transferring data. If tasks are not synchronized, 
the data can be lost during task-to-task communication. You must provide your own 
error-handling routines. The DLX software informs your task of any errors, but your 
task must be written to process error recovery. 

You can use DLX QIOs to communicate between your program and a program on an 
adjacent node using the DECnet DDCMP protocol or the Ethernet. The adjacent 
system can be any DECnet-RSX or non-DECnet based system that has similar capa- 
bilities. In task-to-task communication between adjacent nodes, DLX significantly 
improves network performance in terms of CPU and line usage. You can build your 
own user level protocol that best suits the application. 

NOTE 

All messages transmitted and received via DLX are buffered in net- 
work buffers. In previous versions of DECnet-RSX, user programs 
needed to define buffer space for user data as well as protocol over- 
head using the DLXBUF macro. This is no longer required. 
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4.1 System Requirements for Tasks Using DLX 

Running programs which use the DLX interface requires some special considerations. 

• The DLX process must be loaded. DLX is loaded in the system as a common area 
called NT.DLX. It will normally be resident after loading the network with an NCP 
or VNP command (for example, NCP SET SYSTEM or VNP SET SYSTEM com- 
mand). 

• Prior to running the program, it is necessary to set the line states for the devices the 
program will use. The details for setting lines are described for Ethernet and non- 
Ethernet devices. 

If the program will use a non-Ethernet device, it is necessary to use the following 
commands. The variable dev-x identifies a specific line (for example, DMC-0). 

>NCP SET LINE dev-x 

>NCP SET LINE dev-x OWNER DLX 

>NCP SET LINE dev-x STATE ON 

Now you are ready to run the program. 

If the program will use an Ethernet device, it is necessary to use the following com- 
mand. The variable dev-x identifies a UNA or QNA device (for example, UNA-1). 

>NCP SET LIN dev-x 

Now you are ready to run the program. 

4.2 Special Considerations for Ethernet Users 

The Ethernet is unlike other data links supported by the Communications Executive 
(CEX) and DECnet in that a single circuit can be used by more than one user 
simultaneously. Externally, Ethernet devices appear to be single line point-to-point 
controllers (for example, UNA-0, UNA-1). Internally, they are implemented as mul- 
tipoint devices, with each station representing an available port onto the Ethernet. 

Because the Ethernet allows multiple users to access the physical link simultane- 
ously, some mechanism must be provided to deliver received messages to the correct 
user. All messages on the Ethernet must include a destination address (48-bit) and a 
protocol type (16-bit). There are two modes that determine how messages will be 
transmitted: physical address mode and multicast address mode. 

Physical address mode defines a unique address for a single node on any Ethernet. 
Multicast address mode defines a multidestination address of one or more nodes on a 
given Ethernet. With multicast addressing, any number of nodes can be assigned a 
group address so they are all able to receive the same data in a single transmission. 
Before transmitting and receiving messages, you must define a specific mode. To do 
this, use the SET CHARACTERISTICS (IO.XSC) QIO call (Section 4.3.2). 
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Each user must enable unique protocol/address pairs to define which messages it 
wishes to receive. For example, user 1 may enable protocol A to addresses 1 and 2, 
while user 2 may enable protocol B to addresses 3 and 4. It is possible for two or more 
users to enable the same protocol or addresses, providing that the protocol/address 
pairs are unique. 

The Ethernet may be opened in three different modes (defined in EPMDF$ in NET- 
LIB.MLB): 

• Exclusive - This user has exclusive use of the specific protocol and no other user 
LF$EXC may transmit or receive using this protocol. (DECnet routing uses this 

mode.) 

• Default - This user should receive messages on this protocol that would other- 
LF$DEF wise be discarded because there was no protocol/address pair set up. 

• Normal - The user must specify the protocol/address pairs that will be used for 

communications . 

In addition, the user can select padding for an Ethernet (LF$PAD) that will prefix the 
message with a 2-byte length field and pad the message out to the minimum Ethernet 
size on transmit. On receive, the length field will be used to indicate the amount of 
data present. 

When a hardware error is detected on the Ethernet controller, all protocol/address 
pairings and multicast addresses will be lost. After issuing the IO.XIN call to reini- 
tialize the channel, the protocol/address pairs and the multicast addresses must be 
reenabled. 

Ethernet users should refer to the DECnet-RSX Network Concepts and Procedures 
manual for more information. 



4.3 DLX QIOs 

DLX requests conform to normal RSX-11 QIO standards. Standards for logical unit 
numbers (LUNs), event flags, I/O status blocks, asynchronous system traps (ASTs), 
and parameter lists are observed. According to RSX-11 standards, any one of the 
three macro formats may be used (see Section 2.1). The QIO wait option (specified as 
QIO W$) also may be used to suspend further execution of the program until the call 
completes. 

The macros are defined in the DECnet macro library (NETLIB.MLB). This library is 
transferred to the user's system during NETGEN. The definitions and offsets used in 
the macros are contained in two definition macros: DLXDF$ and EPMDF$. 

It is necessary to issue .MCALL statements and explicitly invoke the macro in the 
user program. For example, 



MCALL DLKDF* »EPMDF* 



DLXDF* 

EPMDF* 
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The DLX QIO codes and functions are summarized in Table 4-1 for both Ethernet 
and non-Ethernet. Each call, with its arguments and completion status codes, is 
described in this chapter (Sections 4.3.1 through 4.3.7). 



Table 4-1: Summary of DLX Function Codes 



Code 


Non-Ethernet 


Ethernet 


IO.XOP 


Open a line 


Open the Ethernet device 


IO.XSC 


Not Applicable 


Set characteristics 


IO.XIN 


Initialize the line 


Not Applicable 


IO.XTM 


Transmit a message 


Transmit a message 


IO.XRC 


Receive a message 


Receive a message 


IOXHG 


Hang up the line 


Not Applicable 


IO.XCL 


Close the line 


Close the line 
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IO.XOP 



Open a Line 



4.3.1 IO.XOP - Open a Line 

Use: 

Issue this QIO to open a line for direct line access message transfer and reception. 
This QIO causes the specified LUN to be associated with the specified line. The 
line is then implicitly initiated, and the protocol is started. The line owner must 
be DLX; the line must be either ON or in SERVICE state, and the LUN must 
have been assigned to NX:. Note that in normal mode (see the p3 argument, 
below), this function will not complete until the task at the other end of the line 
also performs an open or initialize function. 

To open the Ethernet device from DLX, specify the address in argument pi for 
the device ID string (for example, UNA-0). DLX will scan the port database for 
an available port and assign it to DLX for the user. 

Format: 

QIO$ lO.XOP,lun,[efnl,[status],[ast},<pl,p2,p3> 
Arguments: 
IO.XOP 

is the function code that opens a line. 
lun 

is the logical unit number associated with the line that you are opening. 

efn 

is an optional event flag number set when the call completes. 

status 

is the address of an optional 2 -word status block that contains the completion 
status of the call in the low-order byte of the first word (see completion status, 
below). 

ast 

is the entry point into an optional user-written AST routine to be executed after 
this call completes. 
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pi 

is the address of an ASCII string that identifies the line to be opened. 

For non-Ethernet devices the format is: 

dev-ctl[-line][.tributary] 

where dev is the device mnemonic, ctl is the decimal value for the controller 
number, line is the decimal number of the line you are opening, and tributary 
defines the decimal number of the multipoint tributary with which you want to 
communicate. 

p2 

is the length of the line identification field. 
For Ethernet devices, the format is: 

deu-ctl 

where dev is UNA or QNA, and ctl is the decimal value for the controller number. 

p3 

is a word argument that specifies the line mode and timeout value for the call. 
(The timeout value is the amount of time that the receiver waits for a message to 
be transmitted.) The low-order byte of the word designates the receive timeout 
value as follows: 

timeout = for no receive timer. 

timeout = <n> 

where n is the timer value in seconds. (The timer value n causes the timeout to 
have a range of n-1 to n.) The high-order byte of this word designates the line 
mode as follows: 

mode = for normal mode. 

mode = 1 for Maintenance Operation Protocol (MOP) mode. 
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Completion Status. 



IS. SUC (1) The line has been opened successfully. 



177736 The specified LUN is already in use. 

IE.ALN 

(-34.) 

177776 The LUN is not assigned to NX. 

IE.IFC 

(-2.) 

177646 Either you have entered an invalid line identification format or the specified line 

IE.NSF is not in the system. 

(-26.) 

177760 The specified line is not available for use by DLX. 

IE.PRI 

(-16.) 

177757 The specified line is already in use. 

IE.RSU 

(-17.) 
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IO.XSC 



Set Characteristics 



4.3.2 IO.XSC - Set Characteristics (Ethernet Only) 
Use: 

Use this Ethernet QIO to set up the protocol/address pairs and multicast ad- 
dresses. 

Format: 

QIO$ 10. XSC,lun,[efn]„ [status], [ast],<pl,p2> 
Arguments: 
IO.XSC 

is the function code that supplies a single characteristics buffer in arguments pi 
and p2. This buffer may contain multiple characteristics blocks. 

lun 

is the logical unit number associated with the line that you are setting for a 
characteristics buffer. 

efn 

is an optional event flag number set when the call completes. 
status 

is the address of a 2-word status block that contains completion status. On com- 
pletion, the second word of the I/O status block will indicate how much of the 
characteristics buffer has been processed. 

ast 

is the entry point into an optional user-written AST routine to be executed after 
this call completes. 

Pi 

is the address of the characteristics buffer. 
p2 

is the length of the characteristics buffer. 

The set characteristics buffer format may contain multiple characteristics blocks. 
Each characteristics block has the following format: 
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CHARACTERISTICS TYPE 



SIZE OF DATA INPUT 



RESERVED 



CHARACTERISTICS STATUS 



CHARACTERISTICS DATA 



C.TYP 

C.DATI 

C.DATO 

C.STAT 
C.CHRL 



Common error codes in C.STAT are: 

CE.UDF Undefined function 

CE.RTS Request too small (not enough data supplied) 
CE.RTL Request too large (too much data supplied) 
CE.RES Resource allocation failure 

The size of data input (C.DATI) indicates how many bytes of characteristic data are 
being supplied, the size of data output (C.DATO) is not used by this function. The 
status field (C.STAT) of those characteristics blocks that have been processed will be 
set to indicate the success or failure of the characteristics function. Protocol flags are 
defined in EPMDF$ (LF$xxx). 

NOTE 

The address field(s) should not be present if LF$EXC or LF$DEF is 
specified in the flags. 
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Setting up protocol/address pairs: 

Protocol type = CC.DST (200) — allows transmission and reception of messages with 
the specified protocol to/from any of the addresses in the list. 



CHARACTERISTICS TYPE 



SIZE OF DATA INPUT 



RESERVED 



CHARACTERISTICS STATUS 



PROTOCOL TYPE 



PROTOCOL FLAGS 



ADDRESS 1 



ADDRESS n 



C.TYP 
C.DATI 
C.DATO 
C.STAT 



C.CHRL 



CHARACTERISTICS 
DATA 



4+6 n 
BYTES 



Errors returned in C.STAT are: 

CE.PCN Protocol usage conflict: 

A. Another user has exclusive access to this protocol. 

B. There is already a default user of this protocol and this request is 
attempting to set up a new default user. 

C. The padding status of this protocol does not match that which is 
requested. 



CE.IUN 

CE.ACN Address usage conflicts; the protocol/address pair is already in use 



Illegal use of multicast address; one of the addresses specified is multi- 
cast. 
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Setting up a multicast address: 

Protocol type = CC.MCT (201) — 
specified multicast address. 



allows reception of messages that are sent to the 



CHARACTERISTICS TYPE 
SIZE OF DATA INPUT 
RESERVED 
CHARACTERISTICS STATUS 
MULTICAST ADDRESS 



Errors returned in C.STAT are: 

CE.NMA Not a multicast address. 
CE.MCE Multicast address already enabled. 



C.TYP 
C.DATI 
C.DATO 
C.STAT 

CHARACTERISTICS 
DATA 

I 6 BYTES 
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IO.XIN 



Initialize the Line 

4.3.3 IO.XIN - Initialize the Line (non-Ethernet only) 
Use: 

Issue this QIO to reinitialize a line after a fatal device error has occurred. When 
you use this QIO, you must reset the mode and timer values. Note that in normal 
mode (see the pi argument, below), this function will not complete until the task 
at the other end of the line also performs an open or initialize function. 

Format: 

QIO$ 10. XIN,lun,[efn]„[status], [ast], <pl> 
Arguments: 
IO.XIN 

is the function code that initializes the line. 
lun 

is the logical unit number associated with the line that you are initializing. 
efn 

is an optional event flag number set when the call completes. 

status 

is the address of an optional 2-word status block that contains the completion 
status of the call in the low-order byte of the first word (see completion status, 
below). 

ast 

is the entry point into an optional user-written AST routine to be executed after 
this call completes. 

Pi 

is both the mode and timer argument. Use the same format as described for 
argument p3 in IO.XOP (Section 4.3.1). 



4-12 



DECnet-RSX Programmer's Reference Manual 



Completion Status: 



IS. SUC (1) The line has been successfully initialized. 

177761 The initialization attempt has been aborted. This could have been caused by a 

IE. ABO hardware device error, a user-issued hang-up QIO, or an attempt to initialize a 

(-15.) line that was not hung up. 

177776 The LUN is not assigned to NX. 

IE.IFC 

(-2.) 

177733 No line has been opened with the specified LUN. 

IE.NLN 

(-37.) 
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IO.XTM 



Transmit a Message 
on the Line 

4.3.4 IO.XTM - Transmit a Message on the Line 
Non-Ethernet Use: 

Issue this QIO to transmit a message on a line that has been initialized (see Section 
4.3.3). The data that you transmit to the adjacent node is transferred from your user 
buffer and copied to a network buffer for transmission. 

Ethernet Use: 

When transmitting a message on the Ethernet, you must specify the destination 
address for the multicast address to be used for this message along with the protocol 
type. This is accomplished by having an optional auxiliary characteristics buffer for 
transmit in arguments p3 and p4. 

Format: 

QIO$ IO.XTM, lun, [efn]„ [status] , [ast],<pl,p2, [p3,p4] > 
Arguments: 
IO.XTM 

is the function code for transmitting a message. 
lun 

is the logical unit number for the line on which you are transmitting data. 
efn 

is an optional event flag number set when the call completes. 
status 

is the address of an optional 2-word status block that contains the completion 
status of the call in the low-order byte of the first word (see completion status, 
below). 

ast 

is the entry point into an optional user-written AST routine to be executed after 
this call completes. 

Pi 

is the address of the user buffer that contains the message to be transmitted. Use 
the label specified in the DLXBUF macro call. 
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P 2 

is the length of the message you are sending to the remote node (excluding the 
DDCMP header and checksum). 

P 3 

is the address of the optional auxiliary characteristics buffer multicast addresses. 
p4 

is the length of the optional auxiliary characteristics buffer. 

The auxiliary characteristics buffer has the same format as the set characteristics 
buffer described in Section 4.3.2. The individual characteristics block has the follow- 
ing format: 

To set the Ethernet address: 

Protocol type = CC.ADR (100) 



CHARACTERISTICS TYPE 



SIZE OF DATA INPUT 



SIZE OF DATA OUTPUT 



CHARACTERISTICS STATUS 



ETHERNET ADDRESS 



C.TYP 
C.DATI 

C.DATO 
C.STAT 



CHARACTERISTICS 
DATA 



6 BYTES 
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To set the protocol type: 

Protocol type = CC.PRO (101) 



CHARACTERISTICS TYPE 



SIZE OF DATA INPUT 



SIZE OF DATA OUTPUT 



CHARACTERISTICS STATUS 



PROTOCOL TYPE 



C.TYP 

C.DATI 

C.DATO 

C.STAT 

1 CHARACTERISTICS 

DATA 2 BYTES 



Transmit requests on Ethernet channels must include an auxiliary characteristics 
buffer including both the address and protocol type. Failure to do so will cause the 
transmit message to be returned with a IE. BAD error. If the auxiliary buffer is present 
for other data links, the individual characteristics blocks will be completed with a 
CS.IGN (Successful, block ignored) error in C.STAT. 

Completion Status: 

IS. SUC (1) The message was transmitted to the remote node successfully. 

The transmission was aborted because you or the remote user issued a hang-up 
QIO or because an unrecoverable error occurred in the hardware device. When a 
message transmission completes with an IE.ABO code, the line is hung up. You 
must either issue a QIO to initialize the line (see Section 4.3.3) or close and 
reopen the line (see Sections 4.3.7 and 4.3.1, respectively) before you can use 
that line again. 

The hardware device was not ready. The line was hung up and has not been 
reinitialized. 



177761 

IE.ABO 

(-15.) 



177775 
IE.DNR 
(-3.) 

177776 
IE.IFC 
(-2.) 

177733 

IE.NLN 

(-37.) 

177772 

IE.SPC 

(-6.) 



The LUN is not assigned to NX. 



No line has been opened with the specified LUN. 



The transmit buffer is too large (applicable only to PDP-11/44 or PDP-11/70 
with extended memory). 
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IO.XRC 



Receive a Message 
on the Line 

4.3.5 IO.XRC - Receive a Message on the Line 
Non-Ethernet Use: 

Issue this QIO to receive a message from the remote node on a line that has been 
initialized (see Section 4.3.3). Unless you issue a receive QIO, any data sent to 
you by a remote node is lost. When you open a line in MOP (Maintenance 
Operation Protocol) mode, this loss of data is not reported to you. If, however, you 
open the line in normal mode, an error is reported to you the next time you issue a 
receive QIO. 

Ethernet Use: 

When receiving a message on the Ethernet, you must find out the source address 
for this message along with the protocol type. This is accomplished by having an 
optional auxiliary characteristics buffer for receive messages in parameters p3, 
and p4. 

Format: 

QIO$ IO.XRC,/im, [efn]„[status],[ast],<pl,p2, [p3,p4] 
Arguments: 
IO.XRC 

is the function code for receiving a message. 
lun 

is the logical unit number associated with the line on which you receive the 
message. 

efn 

is an optional event flag number set when the call completes. 

status 

is the address of an optional 2-word status block that contains the completion 
status of the call in the low-order byte of the first word (see completion status, 
below). 

ast 

is the entry point into an optional user-written AST routine to be executed after 
this call completes. 

pl 

is the address of the user buffer in your system that receives the message. 
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p2 



is the length in bytes that you are allocating for the receive buffer. (The received 
message cannot be longer than the size of the system buffer, regardless of the 
length you state here for p2.) 

p3 

is the address of the optional auxiliary characteristics buffer. 
p4 

is the length of the optional auxiliary characteristics buffer. 

The auxiliary characteristics buffer has the same format as the set characteristics 
buffer described in Section 4.3.2. The individual characteristics block has the follow- 
ing format: 

To read the Ethernet address: 

Protocol type = CC.ADR (100) 



CHARACTERISTICS TYPE 



SIZE OF DATA INPUT 



SIZE OF DATA OUTPUT 



CHARACTERISTICS STATUS 



ETHERNET ADDRESS 



C.TYP 
C.DATI 

C.DATO 
C.STAT 



CHARACTERISTICS 
DATA 



6 BYTES 
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To read the protocol type: 

Protocol type = CC.PRO (101) 



CHARACTERISTICS TYPE 



SIZE OF DATA INPUT 



SIZE OF DATA OUTPUT 



CHARACTERISTICS STATUS 



PROTOCOL TYPE 



C.TYP 
C.DATI 
C.DATO 
C.STAT 

1 CHARACTERISTICS 

DATA 2 BYTES 



To read destination Ethernet address: 

Protocol type = CC.DAD (102) 



CHARACTERISTICS TYPE 



SIZE OF DATA INPUT 



SIZE OF DATA OUTPUT 



CHARACTERISTICS STATUS 



DESTINATION 
ETHERNET ADDRESS 



C.TYP 
C.DATI 
C.DATO 
C.STAT 



CHARACTERISTICS 
DATA 



6 BYTES 
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Completion Status: 



IS.SUC (1) 

177761 

IE.ABO 

(-15.) 



177763 

IE.DAO 

(-13.) 



177775 

IE.DNR 

(-3.) 

177776 
IE.IFC 
(-2.) 

177733 

IE.NLN 

(-37.) 

177641 

IE.TMO 

(-95.) 

177774 

IE.VER 

(-4.) 
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You successfully received a message from the remote node. The second word of 
the I/O status block contains the number of bytes you actually received. 

The receive function was aborted because you or the remote user issued a hang- 
up QIO or because an unrecoverable error occurred in the hardware device. 
When a receive is aborted, the line is hung up. You must either issue an initial- 
ize QIO (see Section 4.3.3) or close and reopen the line (see Sections 4.3.7 and 
4.3.1, respectively) before you can use the line again. 

Either a message was received before a receive QIO was issued and the data is 
lost (this applies only to normal mode operations), or the user buffer was too 
small to receive all of the data. In the latter case, the message is truncated, and 
some data is lost. (The length of the user buffer is contained in the second word 
of the I/O status block.) 

The hardware device was not ready. The line was hung up and has not been 
reinitialized. 



The LUN is not assigned to NX. 

No line has been opened with the specified logical unit number. 

A timeout condition has occurred. No message was received within the timer 
interval specified when you opened or initialized the line. 

An error has occurred on the line. The second word of the I/O status block 
contains the error code. Possible error codes and their meanings are: 

100361 DDCMP transmit error threshold exceeded 

100362 Operation aborted 

100363 Message received without receive pending 

100364 Start received 

100366 Line physically disconnected 

100370 General error 

100372 MOP message received 

100374 DDCMP reply timeout threshold exceeded 

100376 DDCMP receive error threshold exceeded 
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Hang Up the Line 

4.3.6 IO.XHG - Hang Up the Line (non-Ethernet only) 
Use: 

Issue this QIO to stop operations on a line. This QIO does not close a line. 
However, you must issue an initialize QIO (see Section 4.3.3) or close and reopen 
QIOs (see Sections 4.3.7 and 4.3.1, respectively) to resume operations. 

Format: 

QIO$ IO.XHG, lun, [efn]„[status] , [ast] 
Arguments: 
IO.XHG 

is the function code that hangs up the line. 
lun 

is the logical unit number associated with the line you are hanging up. 
efn 

is an optional event flag number set when the call completes. 
status 

is the address of an optional 2-word status block that contains the completion 
status of the call in the low-order byte of the first word (see completion status, 
below). 

ast 

is the entry point into an optional user-written AST routine to be executed after 
this call completes. 

Completion Status: 

IS. SUC (1) This line was hung up successfully. 

177776 The LUN is not assigned to NX. 

IE.IFC 

(-2.) 

177733 No line has been opened with the specified LUN. 

IE.NLN 

(-37.) 
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IO.XCL 



Close the Line 

4.3.7 IO.XCL - Close the Line (non-Ethernet only) 
Use: 

Issue the IO.XCL call to close an open line and stop the protocol. If you have a 
dial-up connection, however, the line will not be hung up before it closes. 

Format: 

QIO$ IO.XCL, lun, [efn] , , [status] , [ast] 
Arguments: 
IO.XCL 

is the function code that closes the line. 
lun 

is the logical unit number associated with the line that you are closing. 

efn 

is an optional event flag number set when the call completes. 

status 

is the address of an optional 2-word status block that contains the completion 
status of the call in the low-order byte of the first word (see completion status, 
below). 

ast 

is the entry point into an optional user-written AST routine to be executed after 
this call completes. 

Completion Status: 

IS. SUC (1) The line has been successfully closed. 

177776 The LUN is not assigned to NX. 

IE.IFC 

(-2.) 

177733 No line has been opened with the specified LUN. 

IE.NLN 

(-37.) 
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4.3.8 DLX QIO Transmit Programming Example (for non-Ethernet 
device) 

The following programs are examples of tasks using the DECnet-RSX DLX interface. 
XTS-DLX TRANSMITTER uses DLX QIOs to send data. XTR-DLX RECEIVER 
uses DLX QIOs to receive messages. 

NOTE 

These programming examples are also included in your tape or disk 
kit. 



.TITLE XTS - DLX TRANSMITTER 
. I DENT /VOL 01/ 



COPYRIGHT (C) 1983, 1985 BY 

DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 



THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 
TRANSFERRED. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 
CORPORATION. 

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 



MODULE DESCRIPTION: 

XTS - DLX TRANSMITTER 



DISTRIBUTED SYSTEMS SOFTWARE ENGINEERING 
I DENT HISTORY: 

1.00 2 8 -OCT- 8 3 
VERSION 1.0 RELEASE 

1.01 ll-MAR-85 

Correct build procedure UICs 



(continued on next page) 



DLX: Direct Line Access Controller 



4-23 



+ 



XTS - DLX SYSTEM EXERCISER (THIS TEST UTILITY IS UNSUPPORTED) 

XTS IS A UITILITY WHICH ENABLES A USER TO TRANSMIT DATA READ IN FROM 
A TERMINAL OR COMMAND FILE ACROSS AN "ERROR FREE" 

LINE TO A RECEIVER TASK WHICH ECHOES THE RECEIVED DATA BACK OVER THE 
CHANNEL. XTS USES THE DLX INTERFACE TO PROVIDE THE "ERROR FREE" CHANNEL. 

BREAK THROUGH WRITES MUST BE SUPPORTED IN ORDER TO RUN THIS PROGRAM. 



TO ASSEMBLE USE THE FOLLOWING COMMAND STRING: 

MAC XTS ,XTS/-SP/LI :TTM=IN: [130 , 10 ]NETL IB/ML, IN: [200 , 200 ]XTS 

TO TASK BUILD USE THE FOLLOWING COMMAND STRING: 

XTS , XTS/-SP-XTS ,IN:[130,10] NETL I B/LB : GCL 
/ 

STACK- 30 
UNITS=4 

ASG=TI:1:2:3:4 
TASK=. . .XTS 

// 

NOTE: THE IN: DEVICE MUST BE THE DECNET DISTRIBUTION DEVICE 
AFTER THE PREGEN (IF ANY) HAS BEEN PERFORMED. 



THE FOLLOWING IS AN EXAMPLE OF THE XTS DIALOG: 
>XTS 

LINE: DMC-0 

XTS>THIS IS A TEST OF XTS-XTR 
THIS IS A TEST OF XTS-XTR 

XTS>TESTING 
TESTING 

XTS>~Z 
> 

IN ORDER FOR XTS TO RECEIVE AN ECHO OF THE MESSAGE, XTR MUST BE RUNNING. 
IT IS INITIATED IN THE FOLLOWING MANNER: 

>XTR 

LINE: DUP-0 

WHEN FINISHED WITH XTS/XTR, XTR MUST BE ABORTED 



. SBTTL LOCAL MACROS 

.MACRO EPRINT ERRMSG 

MOV # ERRMSG, R0 

CALL $ EPRINT 

. ENDM EPRINT 
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. SBTTL MACRO CALLS 

. MCALL QIOW$ , QIO$ , QIOW$S , ALUN$S , EXIT$S, EXST$S , FSRSZ$ , ASTX$S 

. MCALL GCL $ , GCLDF $ , C ALLR , DLXDF $ 

DLXDF$ ; DEFINE, DLX FUNCTION CODES 



.SBTTL CONSTANTS 



LUN ASSIGNMENTS: 



TILUN=1 
CHNLUN=2 
ERRLUN=3 
CMDLUN=4 

EVENT FLAG ASSIGNMENTS: 

TIEFN=1 
CHNEFN=2 
ERREFN=3 
CMDEFN=4 



;LUN FOR TI 

;LUN FOR ERROR FREE CHANNEL 

;LUN FOR ERRORS 

;LUN FOR COMMAND LINES 



; EVENT FLAG FOR TERMINAL I/O 

; EVENT FLAG FOR CHANNEL 

; EVENT FLAG FOR ERROR MESSAGES 

; EVENT FLAG FOR COMMAND LINES 



.SBTTL DATA 

; DEFINE GCL PARAMETERS 

GCLDF $ CMDLUN, CMDEFN, <XTS>,CMDBUF, 80 . 

; DEFINE FSR SIZE 

FSRSZ$ 1 ;ROOM FOR 1 FILE (GCL) 

. **** 

; DPB'S 
. **** 



WRITE: 


QIOW$ 


IO.WVB,TILUN,TIEFN, , , ,<0,0,40> 


ERDPB: 


QIOW$ 


I . WVB , ERRLUN , ERREFN , , , ,<0,0,40> 


REC1: 


QIO$ 


IO.XRC r CHNLUN, , ,R1SB, RECAST, <R1BUF, 8 0.> 


REC2: 


QIO$ 


IO.XRC,CHNLUN, , ,R2SB, RECAST, <R2BUF, 8 0.> 


CLOSE: 


QIOW$ 


I . XCL , CHNLUN , CHNEFN 



; EXIT-WITH-STATUS WORD 

EXSTAT: . BLKW 1 ;EXIT STATUS 
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; CHANNEL I/O STATUS BLOCK 
CHNSB : . BLKW 2 



AST SAVED I/O STATUS BLOCK 
IOSB: .BLKW 1 

CHANNEL RECEIVE I/O STATUS BLOCKS 
R1SB: 



.BLKW 
• WORD 
.WORD 



2 

R1BUF 
HNGRC1 



R2SB: 



.BLKW 2 
.WORD R2BUF 
.WORD HNGRC2 



BUFFER FOR COMMAND LINE 



CMDBUF: 



, BLKB 
, EVEN 



82. 



; STATUS OF FIRST RECEIVE 
; ADDRESS OF BUFFER 

; ADDRESS OF RECEIVE POSTING ROUTINE 

; STATUS OF SECOND RECEIVE 
; ADDRESS OF BUFFER 

; ADDRESS OF RECEIVE POSTING ROUTINE 



CHANNEL RECEIVE BUFFERS 
R1BUF: .BLKB 80. 



R2BUF: .BLKB 
.EVEN 



80. 



; TEXT STRINGS: 
. **** 



; HEADER FOR ERROR MESSAGES 
XTSEM: .ASCIZ /XTS ~ / 

TEMPORARY PROMPT 
PROMPT: .ASCIZ <15><12>/LINE: / 



ERROR MESSAGES 

.ENABL LC 

.NLIST BEX 

GCLERR: .ASCIZ /Command line read error/ 

NSFERR: .ASCIZ /No such command file/ 

DLXERR: .ASCIZ /DLX not loaded/ 

OPNERR: .ASCII /Unable to open line — / 

BUFOPN: .BLKB 7 

XMTERR: .ASCII /Error transmitting data — / 

BUFXMT: .BLKB 7 

RECERR: .ASCII /Error receiving data — / 

BUFREC: .BLKB 7 

.LIST BEX 

.EVEN 
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. SBTTL XTS - XTS MAIN LINE 

Y 

XTS — MAIN LINE OF XTS CODE 
XTSEP: : 



MOV 


#EX$SUC,EXSTAT 


• A C CTTUTTT PVTT MTTU CTATTTC 

}AooUNci ciAX 1 Wl In blAlUo 


; ASSIGN LUN TO 


CHANNEL 




ALUN$S 


#CHNLUN,#"NX,#0 




BCC 


10$ 


; 1 F H- p ALL UlSAY 


EPRINT 


DLXERR 


• ET^E ASCtfTME DT.X NOT r.OADEn 


BR 


EXIT 


; AND LEAVE 


• PROMPT USER FOR LINE ID 




10$: MOV 


$CLPMT,-(SP) 


;SAVE CURRENT PROMPT 


MOV 


fPROMPT , $CLPMT 


; PROMPT STRING 


CALL 


GCL 


;GET A COMMAND LINE 


MOV 


(SP)+,$CLPMT 


; RESTORE PROMPT 


BCS 


EXIT 


;IF CS, ASSUME EOF 


TST 


R5 


; BLANK LINE ? 


BEQ 


10$ 


;IF EQ, YES - TRY AGAIN 



OPEN ACCESS TO THE LINE. 





QIOW$S 


#10. XOP , #CHNLUN , #CHNEFN , , #CHNSB , , < R4 , R5 > 




BCS 


15$ 


IF CS, ERROR 




MOVB 


CHNSB,R1 


SUCCESSFUL ? 




BPL 


20$ 


IF PL, YES 




MOV 


#BUFOPN,R0 


ELSE, GET BUFFER ADDRESS 




CLR 


R2 


ZERO SUPPRESSION 




CALL 


$CBOMG 


CONVERT NUMBER 




CLRB 


(R0) 


MAKE STRING ASCIZ 


15$: 


EPRINT 


OPNERR 


OPEN ERROR 




BR 


EXIT 




; HANG 


AN ASYNCHRONOUS READ ON LINE 




20$: 


CALL 


HNGRC1 






CALL 


HNGRC2 






BCS 


EXIT 


IF CS, ERROR 


; GET 


COMMAND LINE 




30$: 


CALL 


GCL 


•GET COMMAND LINE 




BCS 


EXIT 


•IF CS, ASSUME EOF 




TST 


R5 


•EMPTY LINE? 




BEQ 


30$ 


•IF EQ, YES - TRY AGAIN 


• TRANSMIT THE 


BUFFER 






CALL 


XMIT 


•TRANSMIT THE BUFFER 




BCC 30$ 




;IF CC, GET NEXT MESSAGE 


; CLOSE THE LINE 




EXIT: 


DIR$ 


#CLOSE 
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EXIT XTS 



EXST$S EXSTAT ;TRY TO EXIT-WITH-STATUS 

EXIT$S ; ELSE , JUST EXIT 

. SBTTL GCL - GET COMMAND LINE 

y 

**-GCL-GET COMMAND LINE 

THIS ROUTINE IS CALLED TO GET A COMMAND LINE FOR XTS. INPUT CAN BE 

FROM TI: OR AN INDIRECT COMMAND FILE. RETURN WITH C-SET FOR ERROR OR EOF. 

INPUTS: 

NONE 

OUTPUTS: 

R4= ADDRESS OF COMMAND LINE 
R5=SIZE OF COMMAND LINE IN BYTES 
C-BIT SET/CLEARED 

EFFECTS : 



. _ 


R4,R5 MODIFIED. 




GCL: 


GCL$ 




;GET COMMAND LINE 




MOV 


$CLIOS, R5 


; POINT TO I/O STATUS BLOCK 




TSTB 


(R5) 


; ERROR? 




BGT 


40$ 


; I F GT , NO 




CMPB 


#IE.EOF, (R5) 


; END OF FILE? 




BEQ 


30$ 


;IF EQ, YES - SET C AND RETURN 




CMPB 


#IE.ABO, (R5) 


;WAS READ KILLED BY RECEIVE? 




BEQ 


30$ 


;IF EQ, YES - RETURN WITH C-SET 




CMPB 


#IE.NSF, (R5) 


;NO SUCH FILE ERROR? 




BNE 


10$ 


;IF NE, NO 




EPRINT 


NSFERR 


; ELSE , SAY SO 




CALL 


ECHO 


;ECHO COMMAND LINE 




CLR 


R5 


;SET COMMAND LINE LENGTH TO 




BR 


50$ 


; AND RETURN EMPTY 


10$: 


EPRINT 


GCLERR 


; PRINT GET COMMAND LINE ERROR 


20$: 


TSTB 


$CLEVL 


; TERMINAL INPUT? 




BNE 


30$ 


;IF NE, NO - FATAL ERROR 




BR 


GCL 


; ELSE , RE-PROMPT 


30$: 


SEC 




; SET-C 




BR 


50$ 


; AND EXIT 


; GET 


SIZE AND 


ADDRESS OF COMMAND LINE. 




40$: 


MOV 


$CLBUF,R4 


;GET ADDRESS OF COMMAND LINE 




MOV 


2(R5) ,R5 


;GET SIZE OF COMMAND LINE 




CLC 




;SET SUCCESS 



50$: 



RETURN 



; RETURN 
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. SBTTL HNGRC1 - HANG ASYNCHRONOUS READ ON LINE 

**-HNGRCl - HANG AN ASYNCHRONOUS READ ON THE CHANNEL 
**-HNGRC2 - 



INPUTS: 

NONE. 

OUTPUTS: 

RECEIVE HUNG ON LINE 



. ENABL LSB 

HNGRC1 : 

CALL $SAVAL 

DIR$ #REC1 

BCS 10$ 

BR 20$ 

HNGRC2 : 

CALL $SAVAL 

DIR$ #REC2 

BCC 20$ 

10$: EPRINT RECERR 
SEC 

20$: RETURN 

. DSABL LSB 



;SAVE ALL REGISTERS 
;HANG RECEIVE 
;IF CS, ERROR 

; AND CONTINUE IN COMMON CODE 



SAVE ALL REGISTERS 
HANG RECEIVE 

IF CC, SUCCESS 
RECEIVE ERROR 
INDICATE FAILURE 
RETURN 



.SBTTL XMIT - TRANSMIT DATA OVER LINE 

**-XMIT - TRANSMIT DATA OVER LINE 

INPUTS: 

R4 = ADDRESS OF DATA 
R5 = LENGTH OF DATA 

OUTPUTS : 

DATA TRANSMITTED 



XMIT: 



QIOW$S 


# IO . XMT , #CHNLUN , #CHNEFN , , #CHNSB , , <R4 , R5> 


BCS 


10$ 


;IF CS, ERROR 


MOVB 


CHNSB,R1 


; SUCCESSFUL ? 


BPL 


20$ 


;IF PL, YES 


MOV 


#BUFXMT,R0 


; ELSE , GET BUFFER ADDRESS 


CLR 


R2 


;ZERO SUPPRESSION 


CALL 


$CBOMG 


; CONVERT NUMBER 


CLRB 


(R0) 


/MAKE STRING ASCIZ 


EPRINT 


XMTERR 


; TRANSMIT ERROR 


SEC 




; INDICATE FAILURE 


RETURN 
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. SBTTL RECAST - AST FOR CHANNEL READ COMPLETE 
♦♦-RECAST - AST FOR CHANNEL READ COMPLETE 
INPUTS: 

(SP) = ADDRESS OF I/O STATUS BLOCK 
OUTPUTS : 

1. ANOTHER READ HUNG ON CHANNEL (IF LAST RECEIVE SUCCEEDED) 

2. BUFFER READ FROM CHANNEL IS ECHOED ON TERMINAL 



RECAST: 



MOV 


(SP) , IOSB 


SAVE I/O STATUS BLOCK ADDRESS 


MOV 


Rl, (SP) 


SAVE Rl 


MOV 


IOSB,Rl 


GET I/O STATUS BLOCK ADDRESS 


TSTB 


(Rl) 


SUCCESSFUL COMPLETION ? 


BPL 


10$ 


IF PL, YES - WRITE IT OUT 


CALLR 


EXIT 


ELSE, CLOSE LINE AND EXIT 


MOV 


2(R1) ,WRITE+Q.IOPL+2 


SET LENGTH OF BUFFER TO WRITE 


MOV 


4(R1) ,WRITE+Q.IOPL 


SET BUFFER ADDRESS 


DIR$ 


# WRITE 


WRITE BUFFER TO TERMINAL 


CALL 


<§6(R1) 


HANG ANOTHER RECEIVE 


MOV 


(SP)+,R1 


RESTORE Rl 


ASTX$S 







.SBTTL $EPRINT ~ PRINT ERROR MESSAGE 
**-$EPRINT-PRINT ERROR MESSAGE 

PRINTS THE SPECIFIED ERROR MESSAGE PREFIXED BY "XTS — 
SETS THE EXIT-STATUS AS "EX$ERR" . 

INPUTS: 

R0= ADDRESS OF MESSAGE. 

OUTPUTS: 

ERROR MESSAGE PRINTED ON TI: 
EXSTAT = EX $ ERR 

EFFECTS : 

NO REGISTERS MODIFIED. 



$EPRINT: 



PRINT2: 

5$: 

10$: 



. ENABL 


LSB 




MOV 


R0,-(SP) 


;SAVE R0 


MOV 


#EX$ERR, EXSTAT 


;SET EXIT STATUS TO "ERROR" 


MOV 


#44,ERDPB+Q. IOPL+4 


;SET VERTICAL FORMAT TO PROMPT 


MOV 


#XTSEM,R0 


;GET PREFIX MESSAGE 


CALL 


5$ 


; PRINT PREFIX 


MOV 


#53,ERDPB+Q. IOPL+4 


;SET VERT. FORMAT TO OVERPRINT 


MOV 


(SP)+,R0 


; GET ADDRESS OF MESSAGE 


MOV 


R0,ERDPB+Q.IOPL 


;SET ADDRESS OF MESSAGE 


TSTB 


(R0) + 


;NULL BYTE? 


BNE 


10$ 


;IF NE, NO - KEEP LOOKING 


DEC 


R0 


; DON'T COUNT NULL 


SUB 


ERDPB+Q.IOPL,R0 


; CALCULATE LENGTH OF STRING 


MOV 


R0,ERDPB+Q.IOPL+2 


;SET LENGTH OF STRING 


DIR$ 


#ERDPB 


; ISSUE DIRECTIVE 


MOV 


#40,ERDPB+Q. IOPL+4 


; RESTORE VERTICAL FORMAT TO NORMAL 


RETURN 






. DSABL 


LSB 
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. SBTTL ECHO - ECHO COMMAND LINE 
** -ECHO- ECHO COMMAND LINE 

THIS ROUTINE ECHOES THE CURRENT COMMAND LINE IF IT CAME FROM AN INDIRECT 
COMMAND FILE. 

INPUTS: 

$CLEVL= INDICATES COMMAND FILE LEVEL 

$CLBUF=PO INTER TO START OF ASCIZ COMMAND LINE. 

OUTPUTS : 

LINE FEED APPENDED TO TO COMMAND LINE AND COMMAND LINE ECHOED ON TI: 

EFFECTS : 

RO, Rl MODIFIED. 



ECHO: 



10$: 



TSTB 

BEQ 

MOV 

CALL 

RETURN 



$CLEVL 
10$ 

$CLBUF , RO 
PRINT2 



; COMMAND FROM TERMINAL? 
; IF EQ, YES - DON'T ECHO 
; POINT TO COMMAND LINE 
; PRINT LINE ON ERROR LUN 



. END XTSEP 
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4.3.9 DLX QIO Receiver Programming Example (for non-Ethernet 
device) 

The DLXRCV program uses DLX QIOs to receive data for Ethernet devices only. 

NOTE 

This programming example is also included in your tape or disk kit. 



.TITLE XTR - DLX RECEIVER 
.IDENT /VOL 01/ 



COPYRIGHT (C) 1983, 1985 BY 

DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 



THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 
TRANSFERRED. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 
CORPORATION. 

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 



MODULE DESCRIPTION: 

XTR - DLX RECEIVER 



DISTRIBUTED SYSTEMS SOFTWARE ENGINEERING 
IDENT HISTORY: 

1.00 28-JUL-79 
VERSION 1.0 RELEASE 

1.01 ll-MAR-85 

Correct build procedure UICs 
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XTR - DLX SYSTEM EXERCISER (THIS TEST UTILITY IS UNSUPPORTED) 

XTR ECHOES RECEIVED DATA BACK OVER THE CHANNEL. XTR USES THE DLX UTILITY 
TO PROVIDE THE "ERROR FREE" CHANNEL. 

TO ASSEMBLE USE THE FOLLOWING COMMAND STRING: 

MAC XTR,XTR/-SP=IN: [ 130 , 10 ]NETLIB/ML, IN: [200,200]XTR 
TO TASK BUILD USE THE FOLLOWING COMMAND STRING: 

XTR , XTR/-SP=XTR ,IN:[130,10] NETL I B/LB : GCL 

/ 

STACK=30 
UNITS=3 
ASG=TI : 1 : 2 : 3 
TASK=. . .XTR 

// 

NOTE: THE IN: DEVICE MUST BE THE DECNET DISTRIBUTION DEVICE 
AFTER THE PREGEN (IF ANY) HAS BEEN PERFORMED. 

THE FOLLOWING IS AN EXAMPLE OF THE XTS DIALOG: 
>XTS 

LINE: DMC-0 

XTS>THIS IS A TEST OF XTS-XTR 
THIS IS A TEST OF XTS-XTR 

XTS>TESTING 
TESTING 

XTS>~Z 

> 

IN ORDER FOR XTS TO RECEIVE AN ECHO OF THE MESSAGE, XTR MUST BE RUNNING. 
IT IS INITIATED IN THE FOLLOWING MANNER: 

>XTR 

LINE: DUP-0 

WHEN FINISHED WITH XTS /XTR, XTR MUST BE ABORTED 



. SBTTL LOCAL MACROS 

.MACRO EPRINT ERRMSG 

MOV # ERRMSG, R0 

CALL $ EPRINT 

. ENDM EPRINT 

.SBTTL MACRO CALLS 

. MCALL QIOW$,QIO$,QIOW$S,ALUN$S,EXIT$S,EXST$S,ASTX$S,WTSE$S 

. MCALL GCL $ , GCLDF $ , DLXDF $ , DLXBUF 

DLXDF$ ; DEFINE DLX FUNCTION CODES AND OVERHEAD 

(continued on next page) 
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. SBTTL CONSTANTS 



RECEIVE BUFFER SIZE 

BUFSIZ = 90. 

LUN ASSIGNMENTS: 

TILUN=1 
CHNLUN=2 
ERRLUN= 3 

EVENT FLAG ASSIGNMENTS: 

TIEFN=1 
CHNEFN= 2 
ERREFN= 3 
DONE=4 



;LUN FOR TI 

;LUN FOR ERROR FREE CHANNEL 
;LUN FOR ERRORS 



; EVENT FLAG FOR TERMINAL I/O 

; EVENT FLAG FOR CHANNEL 

; EVENT FLAG FOR ERROR MESSAGES 

; EVENT FLAG SIGNALING COMPLETION 



, SBTTL DATA 



DEFINE GCL PARAMETERS 





GCLDF$ 


TILUN, TIEFN, <LINE> , R1BUF , BUFSIZ 


. **** 

; DPB'S 
. **** 






ERDPB: 


QIOWS 


I . WVB , ERRLUN , ERREFN , , , ,<0 r 0,40> 


RECl: 
REC2: 


QIO$ 
QIO$ 


IO.XRC,CHNLUN, , , R1SB , RECAST , <R1BUF , BUFS I Z> 
I O.XRC, CHNLUN, , , R2SB, RECAST , <R2BUF , BUFS I Z> 


XMT: 


QIOW$ 


I . XTM , CHNLUN , CHNEFN , , CHNSB , ,<0,0> 


START: 


QIOW$ 


I . X I N , CHNLUN , CHNEFN , , CHNSB 


CLOSE: 


QIOW$ 


I . XCL , CHNLUN , CHNEFN 


; CHANNEL I/O STATUS BLOCK 


CHNSB: 


.BLKW 


2 


; TEMP 


LOCATION 


TO CONTAIN IOSB ADDRESS 


IOSB: 
TEMP: 


.BLKW 
.BLKW 


1 
1 



CHANNEL RECEIVE I/O STATUS BLOCKS 
R1SB: 



R2SB: 



.BLKW 
.WORD 
.WORD 

.BLKW 
• WORD 
.WORD 



2 

R1BUF 
HNGRC1 

2 

R2BUF 
HNGRC2 



; STATUS OF FIRST RECEIVE 
; ADDRESS OF BUFFER 

; ADDRESS OF RECEIVE POSTING ROUTINE 

; STATUS OF SECOND RECEIVE 
; ADDRESS OF BUFFER 

; ADDRESS OF RECEIVE POSTING ROUTINE 



(continued on next page) 



4-34 



DECnet-RSX Programmer's Reference Manual 



CHANNEL RECEIVE BUFFERS 



DLXBUF R1BUF,BUFSIZ ; FIRST BUFFER DESCRIPTOR 

DLXBUF R2BUF,BUFSIZ ; SECOND BUFFER DESCRIPTOR 

. EVEN 

. **** 

'; TEXT STRINGS: 
. **** 

; HEADER FOR ERROR MESSAGES 
XTREM: .ASCIZ /XTR -- / 

; ERROR MESSAQES 





. ENABL 


LC 




.NLIST 


BEX 


GCLERR: 


.ASCIZ 


/Command line read error/ 


DLXERR: 


•ASCIZ 


/DLX not loaded/ 


OPNERR: 


.ASCII 


/Unable to open line -- / 


BUFOPN: 


. BLKB 


7 


XMTERR: 


.ASCII 


/Error transmitting data - 


BUFXMT : 


.BLKB 


7 


RECERR: 


.ASCII 


/Error receiving data — / 


BUFREC: 


.BLKB 


7 




.LIST 


BEX 




• EVEN 






. SBTTL 


XTREP - XTR MAIN LINE 


; + 

; XTREP 


— MAIN 


LINE OF XTR CODE 



PROMPT USER FOR LINE TO OPEN AND LOOP ALL MESSAGES RECEIVED OVER THE SAME LINE 

INPUTS: 

NONE. 

OUTPUTS: 

LOOP ALL MESSAGES INDEFINITELY. 



XTREP: : 

CLR R3 

ASSIGN LUN TO CHANNEL 

ALUN$S fCHNLUN , # " NX , # 

BCC 10$ 

EPRINT DLXERR 

BR 99$ 



;IF CC, ALL OKAY 

; ELSE , ASSUME DLX NOT LOADED 

; AND LEAVE 
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PROMPT USER FOR LINE ID 



10$: 



CALL 
BCS 
TST 
BEQ 



GCL 
99$ 
R5 
10$ 



;GET A COMMAND LINE 

;IF CS, ASSUME EOF 

; BLANK LINE ? 

•IF EQ, YES - TRY AGAIN 



OPEN ACCESS TO THE LINE. 





QIOW$S 


#IO.XOP,#CHNLUN,#CHNEFN, ,#CHNSB, ,<R4,R5> 




BCS 


15$ 




IF CS, ERROR 




MOVB 


CHNSB,R1 




SUCCESSFUL ? 




BPL 


20$ 




IF PL, YES 




MOV 


#BUFOPN,R0 




ELSE, GET BUFFER ADDRESS 




CLR 


R2 




ZERO SUPPRESSION 




CALL 


$CBOMG 




CONVERT NUMBER 




CLRB 


(R0) 




MAKE STRING ASCIZ 


15$: 


EPRINT 


OPNERR 




OPEN ERROR 




BR 


99$ 






; HANG 


AN ASYNCHRONOUS READ ON LINE 






20$: 


CALL 


HNGRC1 








BCS 


99$ 




IF CS, ERROR 




CALL 


HNGRC2 




HANG SECOND RECEIVE 




BCS 


99$ 




IF CS, ERROR 


; THE 


REST IS AST DRIVEN. MAKE BELIEVE 


WE ARE WAITING FOR SOMETHING 




WTSE$S 


#DONE 


;WAIT FOR COMPLETION (NEVER 



99$: 



DIR$ #CLOSE 
EXIT$S 



; CLOSE DOWN THE LINE 
;EXIT 



. SBTTL GCL - GET COMMAND LINE 

h 

**-GCL-GET COMMAND LINE 

THIS ROUTINE IS CALLED TO GET A COMMAND LINE FOR XTR. INPUT CAN BE 

FROM TI: OR AN INDIRECT COMMAND FILE. RETURN WITH C-SET FOR ERROR OR EOF. 

INPUTS: 

NONE 

OUTPUTS : 

R4= ADDRESS OF COMMAND LINE 
R5=SIZE OF COMMAND LINE IN BYTES 
C-BIT SET/CLEARED 

EFFECTS : 

R4,R5 MODIFIED. 
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GCL: GCL$ 

MOV $CLIOS,R5 

TSTB ( R5 ) 

BGT 40$ 

CMPB #IE.EOF,(R5) 

BEQ 30$ 

CMPB #IE.ABO,(R5) 

BEQ 30$ 

10$: EPRINT GCLERR 

20$: TSTB $CLEVL 

BNE 30$ 

BR GCL 
30$: SEC 

BR 50$ 

'; GET SIZE AND ADDRESS OF COMMAND L 

40$: MOV $CLBUF,R4 

MOV 2 ( R5 ) , R5 
CLC 

50$: 

RETURN 



GET COMMAND LINE 
POINT TO I/O STATUS BLOCK 
ERROR? 
IF GT, NO 

END OF FILE? 

IF EQ, YES - SET C AND RETURN 

WAS READ KILLED BY RECEIVE? 
IF EQ, YES - RETURN WITH C-SET 

PRINT GET COMMAND LINE ERROR 
TERMINAL INPUT? 
IF NE, NO - FATAL ERROR 
ELSE, RE-PROMPT 
SET-C 
AND EXIT 

NE. 

; GET ADDRESS OF COMMAND LINE 
; GET SIZE OF COMMAND LINE 
;SET SUCCESS 



; GLOBAL RETURN 



. SBTTL HNGRC1 - HANG ASYNCHRONOUS READ ON LINE 
. SBTTL HNGRC2 - HANG SECOND ASYNCHRONOUS READ 

**-HNGREC - HANG AN ASYNCHRONOUS READ ON THE CHANNEL 
**-HNGRC2 - HANG SECOND ASYNCHRONOUS READ ON CHANNEL 



INPUTS: 

NONE. 



OUTPUTS : 

RECEIVE HUNG ON LINE 



HNGRC1 : 



HNGRC2 : 



10$: 
20$: 



. ENABL 


LSB 




DIR$ 


#REC1 


;HANG READ 


BCS 


10$ 


;IF CS, ERROR 


BR 


20$ 


; AND CONTINUE IN COMMON 


DIR$ 


#REC2 


; HANG READ 


BCC 


20$ 


; IF CC RETURN 


EPRINT 


RECERR 


; RECEIVE ERROR 


SEC 




; INDICATE FAILURE 


RETURN 






. DSABL 


LSB 





(continued on next page) 



DLX: Direct Line Access Controller 



4-37 



. SBTTL XMIT - TRANSMIT DATA OVER LINE 

**-XMIT - TRANSMIT DATA OVER LINE 

INPUTS: 

NONE. 

OUTPUTS : 

DATA TRANSMITTED 



XMIT: 



MOV 


R1,-(SP) 


SAVE Rl 


DIR$ 


#XMT 


TRANSMIT DATA 


BCS 


10$ 


IF CS, ERROR 


MOVB 


CHNSB , Rl 


SUCCESSFUL ? 


BPL 


20$ 


IF PL, YES 


MOV 


#BUFXMT , R0 


ELSE, GET BUFFER ADDRESS 


CLR 


R2 


ZERO SUPPRESSION 


CALL 


$CBOMG 


CONVERT NUMBER 


CLRB 


(R0) 


MAKE STRING ASCIZ 


EPRINT 


XMTERR 


TRANSMIT ERROR 


SEC 




INDICATE FAILURE 


MOV 


(SP)+,R1 


RESTORE Rl 


RETURN 






. DSABL 


LSB 





.SBTTL RECAST - AST FOR CHANNEL READ COMPLETE 
** -RECAST - AST FOR CHANNEL READ COMPLETE 
INPUTS: 

(SP) = ADDRESS OF I/O STATUS BLOCK 
OUTPUTS : 

1. ANOTHER READ HUNG ON CHANNEL 

2. BUFFER READ FROM CHANNEL IS ECHOED OVER LINE 



RECAST : 



5$: 
10$: 



MOV 


( SP ) , TEMP 


MOV 


Rl, (SP) 


MOV 


TEMP , Rl 


TSTB 


(Rl) 


BPL 


10$ 


TST 


R3 


BNE 


20$ 


INC 


R3 


DIR$ 


# START 


BCC 


5$ 


IOT 




TSTB 


CHNSB 


BPL 


20$ 


IOT 




CLR 


R3 


MOV 


2(R1) ,XMT+Q. IOPL+2 


BEQ 


20$ 


MOV 


4(R1) ,XMT+Q. IOPL 


CALL 


XMIT 


CALL 


@6(R1) 


MOV 


(SP)+, Rl 


ASTX$S 





SAVE IOSB ADDRESS 
SAVE Rl 
Rl -> IOSB 

SUCESSFUL COMPLETION ? 

IF PL, YES - XMIT THE MESSAGE 

BEEN THRU THIS CODE LAST TIME ? 

YES - POST RECEIVE AND RETURN 

MARK 

ELSE, RESTART THE LINE 
IF SUCCESS, CONTINUE 

ELSE IOT 
SUCCESS ? 
YES - CONTINUE 

ELSE FATAL ERROR - IOT 
CLEAR FLAG 

SET LENGTH OF BUFFER TO XMIT 
IF EQ, NO BUFFER TO XMIT ??? 
SET ADDRESS OF BUFFER 
ECHO MESSAGE BACK OVER LINE 
HANG ANOTHER RECEIVE ON CHANNEL 
IGNORE ANY ERRORS 
RESTORE Rl 
EXIT AST 
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. SBTTL $EPRINT — PRINT ERROR MESSAGE 
**-$EPRINT-PRINT ERROR MESSAGE 

PRINTS THE SPECIFIED ERROR MESSAGE PREFIXED BY "XTR — 
SETS THE EXIT-STATUS AS I, EX$ERR" . 

INPUTS: 

R0= ADDRESS OF MESSAGE. 

OUTPUTS : 

ERROR MESSAGE PRINTED ON TI : 

EFFECTS: 

NO REGISTERS MODIFIED. 



$EPRINT: 



5$: 
10$: 



MOV 


R0,-(SP) 


MOV 


#44,ERDPB+Q. IOPL+4 


MOV 


#XTREM,R0 


CALL 


5$ 


MOV 


#53,ERDPB+Q. IOPL+4 


MOV 


(SP)+,R0 


MOV 


R0 , ERDPB+Q. IOPL 


TSTB 


(R0) + 


BNE 


10$ 


DEC 


R0 


SUB 


ERDPB+Q. IOPL,R0 


MOV 


R0, ERDPB+Q. IOPL+2 


DIR$ 


#ERDPB 


MOV 


#40, ERDPB+Q. IOPL+4 


RETURN 





SAVE R0 

SET VERTICAL FORMAT TO PROMPT 
GET PREFIX MESSAGE 
PRINT PREFIX 

SET VERT. FORMAT TO OVERPRINT 
GET ADDRESS OF MESSAGE 
SET ADDRESS OF MESSAGE 
NULL BYTE? 

IF NE, NO - KEEP LOOKING 
DON'T COUNT NULL 
CALCULATE LENGTH OF STRING 
SET LENGTH OF STRING 
ISSUE DIRECTIVE 

RESTORE VERTICAL FORMAT TO NORMAL 



. END XTREP 
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4.3.10 DLX QIO Programming Example (for Ethernet device) 



The XTR-DLX RECEIVER program uses DLX QIOs to receive data. 

NOTE 

This programming example is also included in your tape or disk kit. 

.TITLE DLXRCV - DLX Receive Program for Ethernet 

. I DENT /VOL 01/ 

. ENABL LC 

.NLIST BEX 



Copyright (C) 1982, 1985 by 

DIGITAL EQUIPMENT CORPORATION, Maynard, MASS. 

This software is furnished under a license for use only on a 
single computer system and may be copied only vith the 
inclusion of the above copyright notice. This software, or 
any other copies thereof, may not be provided or otherwise 
made available to any other person except for use on such 
system and to one who agrees to these license terms. Title 
to and ownership of the software shall at all times remain 
in DEC. 

The information in this document is subject to change without 
notice and should not be construed as a commitment by Digital 
Equipment Corporation. 

DEC assumes no responsibility for the use or reliability of 
its software on equipment which is not supplied by DEC. 



Module Description: 

DLXRCV - DLX receive program for Ethernet 

The following devices are currently supported: 

UNA 

QNA 

This program is used to monitor messages sent by other stations 
on the ethernet. Due to the data rates that are present, it can 
only be used to watch a single protocol type at a time and will 
not be able to keep up if the output device is a terminal or 
printer. This program can not be used concurrently with DECnet 
(XPT) running. 

To assemble this program use the following command line: 
MAC DLXRCV, DLXRCV/-SP=IN: [130, 10 ]NETLIB/ML, IN: [ 200 , 200 ] DLXRCV 

Note: The IN: device must be the DECnet distribution device 
after the PREGEN (if any) has been performed. 

To build the program: 
TKB DLXRCV/PR : , DLXRCV/-SP=DLXRCV 

Ident History: 

1.00 21-Jul-83 
Version 1.0 Release 

1.01 ll-Mar-85 
Correct build UICs 
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.MCALL EXIT$S, QIOW$S, 

.MCALL ASTX$S, SETF$S, 

.MCALL DSAR$S, ENAR$S , 

.MCALL GCMLB$, NMBLK$ , 

.MCALL CSI$, CSI$SW, 

.MCALL FDAT$R, FDRC$R, 

.MCALL DLXDF$, EPMDF$, 



QIO$S, ALUN$S 

CLEF$S, WTSE$S 

SREA$S, QIO$ 

GCML$ , OFNB$ , OFNB$W 

CSI$ND, CSI$1, CSI$2 

FDBF$R, FCSMC$, PUT$S 

CHRDF$ 



FCSMC$ 
DLXDF$ 
CHRDF$ 
EPMDF$ 

Local program constants 



NETLUN 

OUTLUN 

OUTL 

TILUN 

TILEN 

RBUFL 

RBCNT 

REST 



1 
2 

144. 

5 

144. 

1518, 

20. 

18. 



Define the DLX symbols 
Define Get/Set Char symbols 



Network LUN 
Data output LUN 
Length of output line 
Terminal I/O LUN 
Terminal I/O Buffer size 
Receive buffer byte count 
Number of receive buffers 
Rest of the receive line 



. SBTTL Define local macros 
TAGNUM= 



BUF'N: 
BUFL ' N 



.MACRO 


TYPE MSG 


TAGNUM= 


TAGNUM+1 


. NLIST 




. IRP 


N, <\TAGNUM> 


.SAVE 




. PSECT 


DATA1 , D 


.ASCII 


"MSG" 




.-BUF'N 


.EVEN 




. RESTORE 


MOV 


R0,-(SP) 


MOV 


R1,-(SP) 


MOV 


R2,-(SP) 


MOV 


#BUF ' N , Rl 


MOV 


#BUFL'N,R0 


MOV 


#40, R2 


JSR 


PC, PRINT 


MOV 


(SP)+,R2 


MOV 


(SP)+,R1 


MOV 


(SP)+,R0 


• ENDM 




.LIST 




.ENDM 


TYPE 



Save the registers 



Set up pointers for message 



Forms control character 
Go print it 
Restore registers 
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BUF'N: 
BUFL ' N 



BUF'N: 
BUFL ' N 



•MACRO 


ERROR MSG 


TAGNUM= 


=TAGNUM+ 1 


.NLIST 




. IRP 


N,<\TAGNUM> 


.SAVE 




. PSECT 


DATA1 , D 


.ASCII 


"MSG" 




.-BUF'N 


.EVEN 




. RESTORE 


MOV 


R0,-(SP) 


MOV 


R1,-(SP) 


MOV 


R2,-(SP) 


MOV 


#BUF'N,R1 


MOV 


#BUFL'N,R0 


MOV 


#60, R2 


JSR 


PC , ERRPRT 


MOV 


(SP)+,R2 


MOV 


(SP)+,R1 


MOV 


(SP)+ f R0 


. ENDM 




.LIST 




.ENDM 


ERROR 


.MACRO 


PROMPT MSG 


TAGNUM= 


TAGNUM+ 1 


.NLIST 




. IRP 


N, <\TAGNUM> 


.SAVE 




. PSECT 


DATA1 , D 


.ASCII 


"MSG" 




.-BUF'N 


.EVEN 




. RESTORE 


MOV 


#BUF'N,R1 


MOV 


#BUFL'N,R0 


JSR 


PC, ASK 


.ENDM 




.LIST 




.ENDM 


PROMPT 


.MACRO 


PRO TYP 


.LIST 




.WORD 


CC.DST 


.WORD 


4 


.WORD 





.WORD 





.WORD 


TYP 


.WORD 


LF$EXC! LF$DEF 


.NLIST 




. ENDM 


PRO 


.MACRO 


MUL ADl, A 


.LIST 




.WORD 


CC.MCT 


.WORD 


6 


.WORD 





.WORD 





.WORD 


ADl 


.WORD 


AD 2 


.WORD 


AD 3 


.NLIST 




.ENDM 


MUL 


. SBTTL 


Data Area 


. PSECT 


DATA2 , D 



Save the registers 



Set up pointers for message 

Forms control value 
Go print it 
Restore registers 



Set up pointers for message 
Go do it 



Characteristics type 
Input data byte count 
Output data byte count 
Output status 
Protocol type 
Protocol Flags 



Enable multicast address for this prot 
Input data byte count 
Output data byte count 
Output status 
Multicast address 
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For information purposes - Defined in CHRDF$ 
Protocol types 



CP . LOO = 

CP.DUM = 

CP . CON = 

CP . ROU = 



000220 
000540 
001140 
001540 



Loopback (cross-company) 90-00 

Dump/Load (Digital) 60-01 

Remote console (Digital) 60-02 

Routing (Digital) 60-03 



Multicast addresses 



CM.LOl 
CM.L02 
CM.L03 

CM. DM1 
CM. DM2 
CM. DM3 

CM.RC1 
CM.RC2 
CM.RC3 



000317 
000000 
000000 

000253 
000400 
000000 

000253 
001000 
000000 



First word of Loopback CF-00 

Second word 00-00 

Third word 00-00 

First word of Dump/Load AB-00 

Second word 00-01 

Third word 00-00 

First word of Remote console AB-00 

Seconds word 00-02 

Third word 00-00 



Characteristics buffers 

.LIST ME 
CHRLOO: 

PRO CP. LOO 

MUL CM.LOl, CM. L02, CM. L03 

LOOLEN = .-CHRLOO 



Loopback 

Loopback Multicast 



CHRDLL: 

PRO CP.DUM 
MUL CM. DM1, CM. DM2, CM. DM3 

DLLLEN = .-CHRDLL 



; Dump/Load 



CHRRCN: 

PRO CP. CON 

MUL CM.RC1,CM.RC2,CM.RC3 
RCNLEN = .-CHRRCN 



; Remote console 



CHRROU: 



PRO 
MUL 
MUL 
MUL 
MUL 



CP. ROU 

253,1400,0 
253,2000,0 
243,1400,0 
243,2000,0 



ROULEN = .-CHRROU 



; Router 



DEVMDE: .WORD CC.ECM 
.WORD 2 
.WORD 
.WORD 
•WORD 

MDELEN = .-DEVMDE 

PRMMDE = 100000 



Ethernet channel mode 
Two bytes of data 
Data bytes out 
Status 

Mode word for device 



; Promiscuous mode for UNA 
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. SBTTL Receive buffers 

.PSECT DATA 3 , D 

. NLIST ME 

RB=0 

. REPT RBCNT 
RB=RB+1 

.IRP N,<\RB> 



Create the receive buffers 



Receive buffer #'N 
RBUF'N: . BLKB RBUFL 

Buffer for DLX receive set characteristics 
CHR'N: 



Receive buffer 



.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 



CC . DAD 

6 






CC.ADR 

6 






CC . PRO 

2 






CHRL'N = .-CHR'N 

. ENDM 
.ENDR 



IO=0 

. REPT RBCNT 
10=10+1 

.IRP N,<\10> 



BSB'N: 



, BLKW 2 

.WORD 

. WORD RBUF ' N 

. WORD CHR ' N 
BSBL'N = .-BSB'N 

.ENDM 
.ENDR 



.PSECT 
NXIOSB: .BLKW 



TIOSB: 
OUTSB: 



.BLKW 
.BLKW 



BUFCNT: .WORD 



DATA4 , D 

2 

2 

2 





Read destination address 
Input data byte count 
Output data byte count 
Status 

Ethernet address 



Read source Address 
Input data byte count 
Output data byte count 
Status 

Ethernet address 



Read protocol type 
Input data byte count 
Output data byte count 
Status 

Protocol type 



Rec buffer IOSB 
Link word to next descriptor 
Address of the receive buffer 
Address of the characteristics buffer 



Local storage area 
Network I/O status doubleword 
Terminal I/O Status Doubleword 
Output IOSB 

Local count of received packets 
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RCVQUE: .WORD ; Receive queue listhead 

.WORD RCVQUE ; ... 

.WORD -1 ; Temp flag 

TIBUF: . BLKB TILEN ; Terminal I/O Buffer 

OUTBUF : 

.BLKB OUTL ; Output buffer 

DEF: .ASCII /UNA-0/ 

DEFL = .-DEF 

CNTSTR: .ASCII / Total number of packets received / 

CNTL = .-CNTSTR 

.EVEN 



. SBTTL CONSTANTS FOR PROGRAM AND FILE BLOCK ALLOCATION 
MS1.TB=1 



FDBOUT : 



FSRSZ$ 

FDBDF$ 
FDAT$A 
FDRC$A 
FDOP$A 



R. VAR, FD. CR 
, OUTBUF, OUTL 
OUTLUN , DFOUT 



File buffers 

Allocate space for FDB 
File attributes 
Record access mode 
File open section 



LCSIO: 



DFOUT : 



CSI$ 

.BLKB 

.EVEN 



C.SIZE 



NMBLK$ ETHER , DAT ,, SY , 



; Allocates required storage, 



SWTABO: 

CSI$SW TB,MS1.TB ; Tab switch 

CSI$ND ; End of table 



. EVEN 

.SBTTL Main Code 

. PSECT CODE 

. ENABL LSB 

; QIO directives 

XIORCV: QIO$ IO.XRC ,NETLUN, , , , RCVAST , <0 , RBUFL , , CHRL1> 

OUTIO: QIO$ 10. WVB, OUTLUN, 2, ,0UTSB, , <OUTBUF , OUTL , 60> 



START : 

FINIT$ ; Initialize files 

ALUN$S #TILUN,#"TI ; Assign LUN to terminal 

TYPE < UNA Ethernet monitor > 

TYPE < > 

TYPE < The default output is SY: ETHER. DAT > 
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10$; 



20$: 



TYPE 

PROMPT 

MOV 

MOV 

CSI$1 

CSI$2 

FDOP$R 

OPEN$W 

BCC 

ERROR 

JMP 

ALUN$S 
BCC 
ERROR 
JMP 



PROMPT 
BNE 
MOV 
MOV 



<Output Device? (File, TI : or Return) > 

Rl,LCSIO+C.CMLD+2 

R0,LCSIO+C.CMLD 

fLCSIO 

# LCS 1 , OUTPUT , # SWT AB 

#FDBOUT , #OUTLUN , #LCS I O+C . DSDS , #DFOUT 

#FDBOUT 

10$ 

< Could not open file > 
ERREXT 

#NETLUN,#"NX,#0 ; Assign a LUN to DLX 

20$ ; Branch if no error 

<Could not assign LUN to NX > 
ERREXT 



< Enter line (UNA-0) 
30$ 

#DEF , Rl 
#DEFL,R0 



Branch if response 
Get default answer 
And default length 



Open the Line 
30$: 



MOV #NXIOSB,R3 ; Point to network IOSB 

QIOW$S #IO.XOP,#NETLUN,#l, ,R3 , , <R1 , R0 , #400> 



TSTB (R3) 

BPL 40$ 

ERROR < Could not open line > 

CALL PRTOB 

JMP ERREXT 



Get current mode 
40$: 



Get "open" QIO status 
Branch if no error 

Print the error code 
Get out 



Get address of request buffer 



50$: 



MOV #DEVMDE,R4 

QIOW$S #IO.XGC,#NETLUN,#l, ,R3, , <R4 , #MDELEN> 

TSTB (R3) ; Was request successful? 

BPL 50$ ; If PL, Yes 

ERROR < QIO for get device mode failed> 

JMP ERREXT 

CMP #CS.SUC,6(R4) ; Was this request successfull? 

BEQ 60$ ; If EQ,yes 

ERROR < Get device mode request failed> 

JMP ERREXT 

Set device in promiscuous mode 

60$: 

BIS fPRMMDE, 10(R4 ) ; Set promiscuous mode 

QIOW$S #IO.XSC,#NETLUN,#l, , R3 , , <R4 , #MDELEN> 

TSTB (R3) ; Was request successful 

BPL 70$ ; If PL, Yes 

ERROR < QIO for set device mode failed> 

JMP ERREXT 



70$: 



CMP &CS.SUC,6(R4) ; Was this request successfull? 

BEQ 80$ ; If EQ,yes 

ERROR < Set device mode request failed> 

JMP ERREXT 
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80$: 



90$: 



100$: 



PROMPT 


<What do you 


want to 


MOV 


#CHRLOO,R4 




MOV 


#LOOLEN,R5 




CMPB 


# 1 L, (Rl ) 




BEQ 


90$ 




MOV 


#CHRDLL, R4 




MOV 


#DLLLEN,R5 




CMPB 


# ' D , ( Rl ) 




BEQ 


90$ 




MOV 


#CHRRCN,R4 




MOV 


#RCNLEN,R5 




CMPB 


#'C, (Rl) 




BEQ 


90$ 




MOV 


#CHRROU , R4 




MOV 


#ROULEN,R5 




CMPB 


#'R, (Rl) 




BNE 


80$ 




TYPE 


<Warning ! ! I 


may not 


» protocol type to monitor 


MOV 


#NXIOSB,R3 




QIOW$S 


#IO.XSC,#NETLUN,#l, ,1 


TSTB 


(R3) 




BMI 


120$ 




CMP 


#CS.SUC,6(R4) 




BNE 


110$ 




SUB 


2(R4) r R5 




SUB 


#10, R5 




BLE 


140$ 




ADD 


2 ( R4 ) , R4 




ADD 


#10, R4 




BR 


100$ 





Assume loopback 

Do they want loop 
If EQ, Yes 
Try DLL/DUM 

Do they want DLL? 
If EQ,yes 
Remote console 

If EQ, remote console will be displaye 
How about router 

If NE, ask again 



110$: 



120$ 
130$ 



MOV 

ERROR 

MOV 

MOVB 

CALL 

MOVB 

BR 

ERROR 

CALL 
JMP 



Get IOSB address 
U,R5> ; Set the protocol type 
Get "SET CHR" QIO status 
Branch if error 

Was this request successfull? 

If NE, no 

Length of request 

Length of header 

All done 

Point to next request 
Check next one 



R4,-(SP) ; Save request address 

< Set characteristics error - Bad status in buffer > 
(SP)+,R4 ; Restore the request address 
6(R4),R3 ; Get the error code 

PRTOB ; Print the low byte 

7(R4),R3 ; Get the high byte 

130$ 

< Set characteristics error - Set protocol (QIO status) > 



PRTOB 
EXIT 



Post the receive buffers 
140$: 



MOV 
MOV 
DSAR$S 



#BSB1,R1 
#RBCNT,R0 



Print the error code 
Get out 



Pointer to first IOSB 
Number of receive buffers 
Disable AST's 
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150$: 



160$: 



MOV 


R1,4(R1) 


• Fill in link word address 


ADD 


#BSBL1,4(R1) 


of next descriptor 


MOV 


R1,Q. IOSB+XIORCV 


• Fill in IOSB field 


MOV 


6(R1) ,Q. IOPL+XIORCV 


Fill in buffer address 


MOV 


10(R1) ,Q. IOPL+4+XIORCV 


Fill in characteristics buffer address 


DIR$ 


#XIORCV 


Issue the receive request 


BCS 


190$ 


If CS, error with directive 


ADD 


#BSBL1,R1 


Point to next IOSB 


DEC 


R0 


One less to post 


BNE 


150$ 


Loop till done 


SUB 


#BSBL1 , Rl 


Backup pointer to last descriptor 


MOV 


#BSB1,4(R1) 


Change to point to first descriptor 


CLEF$S 


#5 


Clear the event flag 


ENAR$S 




Enable AST's 


SREA$S 


# ABO AST 


Specify an abort AST 


TYPE 


<Monitor Starting... > 




MOV 


4(R1) ,R1 


Get next descriptor address 


TST 


(Rl) 


Has buffer been used? 


BNE 


170$ 


If NE, Yes 


WTSE$S 


#5 


Wait for event 5 (RCV complete) 



; Process the receive buffers 
170$: 



190$: 



CLEF$S 


#5 


Clear the event flag 


INC 


BUFCNT 


Another one received 


TSTB 


(Rl) 


Did rec complete successfully? 


BMI 


200$ 


If MI, Repost the buffer 


MOV 


#OUTBUF,R0 


Output buffer area 


MOV 


10(R1) ,R3 


Get address of the char buffer 


ADD 


#C.CHRL,R3 


Point to destination address 


MOV 


#6,R4 


Number of bytes to convert 


CALL 


CNV 


Convert to ASCII 


MOVB 


#40, (R0)+ 


Add another space 


ADD 


#C.CHRL,R3 


Point to source address 


MOV 


#6,R4 


Number of bytes to convert 


CALL 


CNV 


Convert to ASCII 


MOVB 


#40, (R0)+ 


Add another space 


ADD 


#C.CHRL,R3 


Point to protocol type 


MOV 


#2,R4 


Number of bytes to convert 


CALL 


CNV 


Convert to ASCII 


MOVB 


#40, (R0)+ 


A couple of more spaces 


MOVB 


#40, (R0) + 




MOV 


#REST,R4 


Print out the rest of the line 


MOV 


6(R1) ,R3 


Get address of the data buffer 


CALL 


CNV 


Convert the data to ascii 


CALL 


POST 


Post another receive 


PUT$S 


#FDBOUT 




BCC 


160$ 


Check for error 


ERROR 


< Device write error > 




BR 


EXIT 


Print error and get out 


ERROR 


< Receive directive error > 


MOV 


R1,R3 


• Get IOSB 


CALL 


PRTOB 


Print the error code 


BR 


EXIT 


Get out 
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200$: 

ERROR < Receive buffer error 

MOV Rl , R3 

CALL PRTOB 

CALL POST 

BR 160$ 

. DSABL LSB 



Point to IOSB 
Print the error code 
Post the receive again 
Wait for another completion 



EXIT: 



ERREXT : 



POST: 



CLOSE$ 

MOV 

BIC 

QIOW$S 
QIOW$S 

CLOSE$ 
EXIT$S 



# FDBOUT 

#DEVMDE,R4 

#PRMMDE , 10 ( R4 ) 

#IO.XSC,#NETLUN r ffl, ,R3, 

#IO.XCL,#NETLUN,#l 

# FDBOUT 



(Rl) 
2(R1) 

R1,Q. IOSB+XIORCV 
6(R1) ,Q. IOPL+XIORCV 
10(R1) ,Q. IOPL+4+XIORCV 
#XIORCV 



CLR 
CLR 
MOV 
MOV 
MOV 
DIR$ 
RETURN 

. SBTTL AST routines 

h 

RCVAST Receive buffer AST routine 



; Get address of request buffer 
; Clear promiscuous mode 
,<R4,#MDELEN> ; ... 
; Close the opened line 



Program exits 



Clear out the IOSB 

Fill in IOSB address 

Fill in buffer address 

Fill in characteristics buffer address 

Post the buffer 



RCVAST: 



TST 

SETF$S 
ASTX$S 



(SP) + 
#5 



Remove IOSB address 

Set event flag for rev complete 

Exit from AST 



; ABOAST - AST routine for abort requests 
ABOAST: 



MOV 


#OUTBUF , R0 


; Get output buffer pointer 


MOV 


#CNTSTR,R1 


; Address of count text 


MOV 


#CNTL,R2 


; Get the length 


MOVB 


(Rl)+, (R0)+ 


; Move the characters 


DEC 


R2 




BNE 


10$ 




MOV 


BUFCNT , Rl 


; Get the packet count 


CLR 


R2 


; Suppress leading zeros 


CALL 


$CBDMG 


; Convert to decimal count 


MOV 


#OUTL , Rl 


; Compute the space left 


ADD 


tOUTBUF , Rl 




SUB 


R0,R1 




MOVB 


#40, (R0)+ 


; Fill rest with blanks 


DEC 


Rl 




BNE 


20$ 




PUT$S 


# FDBOUT 




QIOW$S 


#IO.WVB,#TILUN,#7, , 


, ,<#OUTBUF,#OUTL,#60> 


JMP 


EXIT 


; Go close the line 
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. SBTTL TERMINAL I/O SUBROUTINES 

h 

ASK - Prompt and get response 
I nput : 

RO - Length of prompt 

Rl - Address of prompt string 

Output : 

RO - Length of response 

Rl - Address of response string 



ASK: 



10$: 



Z bit set if nothing typed (just a carrige return) 



QIOW$S #IO.RPR,#TILUN,#9. , ,#TIOSB, , <#TIBUF, #TILEN r ,R1,R0 ,#44> 



CMPB 

BNE 

SEC 

RETURN 

MOV 
MOV 
CLC 
RETURN 



TIOSB,#IE.EOF 
10$ 



#TIBUF,R1 
TIOSB+2,R0 



; Was a Ctrl/Z typed? 

; Branch if no 

; Indicate ~Z typed 



; Get buffer address 
; Save byte count in RO 
; Clear the carry 



PRTOB - Print octal data byte 

Inputs: 

R3 - Data Buffer Address 

Outputs: 

Byte printed on TI 
R0,R2 - Destroyed 



PRTOB : 



MOV 

MOVB 

BIC 

ASH 

ADD 

MOVB 

MOVB 

MOVB 

QIOW$S 
RETURN 



#TIBUF,R0 
(R3)+,R2 
#~C<377>,R2 
#2,R2 

#CNVTAB , R2 
( R2 ) + , ( RO ) -t- 
(R2)+, (R0)+ 
(R2)+, (R0)+ 



Output area 

Get data byte 

Clear out high byte 

Convert to table offset 

Add in base address of table 

Get the conversion data 



#IO.WVB,#TILUN,#9. , , , ,<#TIBUF, #3,#40> ; Print the data 



ERRPRT - Print error messages 

PRINT - Print a message on the terminal 



Inputs; 



RO - Length of string 

Rl - Address of error message 

R2 - Forms control value 



ERRPRT : 
PRINT: 



QIOWSS #IO.WVB,#TILUN,#9. , , , , *-Rl ,R0 ,R2> 
RETURN 
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+ 

CNV - Convert binary to ASCII string 



Inputs: 

RO -> Output buffer area 

R3 -> Input buffer of binary data 

R4 - Number of bytes to convert 
Outputs: 

RO -> Next available address in the output area 
R3 -> Next byte after "count" bytes are converted 
- 



R4 

Destroyed R2 



CNV: 



MOVB 

BIC 

ASH 

ADD 

MOVB 

MOVB 

MOVB 

MOVB 

SOB 

RETURN 



(R3)+,R2 

#~C<377>,R2 

#2,R2 

#CNVTAB , R2 
(R2)+, (R0)+ 
(R2)+, (R0)+ 
(R2)+, (R0)+ 
(R2)+, (R0)+ 
R4,CNV 



Get the data byte 

Clear out high byte 

Shift left twice 

Add start of table 

Move the first character 

Second 

Third 

Fourth 

Loop till done 



CNVTAB: 



. BYTE 


60 


60 


60 


40 


000 


. BYTE 


60 


60 


61 


40 


001 


. BYTE 


60 


60 


62 


A f\ 

40 


n r\ *■> 
U(J Z 


. BYTE 


60 


60 


63 


A f\ 

41) 


Ck ft 1 

U U j 


. BYTE 


60 


60 


64 


40 


004 


iOI lei 


DU 


DU 


fit; 


An 


VJ U Q 


. NLIST 












.BYTE 


60 


60 


66 


40 


006 


.BYTE 


60 


60 


67 


40 


007 


.BYTE 


60 


61 


60 


40 


010 


.BYTE 


60 


61 


61 


40 


011 


.BYTE 


60 


61 


62 


40 


012 


.BYTE 


60 


61 


63 


40 


013 


.BYTE 


60 


61 


64 


40 


014 


.BYTE 


60 


61 


65 


40 


015 


.BYTE 


60 


61 


66 


40 


016 


.BYTE 


60 


61 


67 


40 


017 


.BYTE 


60 


62 


60 


40 


020 


• BYTE 


60 


62 


61 


40 


021 


.BYTE 


60 


62 


62 


40 


022 


.BYTE 


60 


62 


63 


40 


023 


.BYTE 


60 


62 


64 


40 


024 


.BYTE 


60 


62 


65 


40 


025 


.BYTE 


60 


62 


66 


40 


026 


.BYTE 


60 


62 


67 


40 


027 


.BYTE 


60 


63 


60 


40 


030 


.BYTE 


60 


63 


61 


40 


031 


.BYTE 


60 


63 


62 


40 


032 


.BYTE 


60 


63 


63 


40 


033 


.BYTE 


60 


63 


64 


40 


034 


.BYTE 


60 


63 


65 


40 


035 


.BYTE 


60 


63 


66 


40 


036 


.BYTE 


60 


63 


67 


40 


037 


.BYTE 


60 


64 


60 


40 


040 


. BYTE 


60 


64 


61 


40 


041 


.BYTE 


60 


64 


62 


40 


042 



; ETC... 
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. BYTE 


60 


64 


fi"} 

D J 


dn 


u ft o 


. BYTE 


fin 

D U 


fid 

Dl 


fid 
Oft 


dn 

ft u 


ndd 

U ft H 


BYTE 


fin 

o u 


fid 
Oft 


fiR 
DO 


dn 

ft u 


flic 

U ft *J 


. BYTE 


fin 

o u 


fid 

ot 


fifi 
D D 


dn 

ft U | 


ndfi 

u ft D 


BYTE 


fin 

o u 


fid 
Oft 


fi7 
D / 


dn 

ft U 


nd7 

U ft / 


BYTE 


60 


fiR 


fin 


dn 


nRn 

U 3U 


. BYTE 


60 


65 


61 


40 


051 


BYTE 


fin 
o u 


fiR 


fi? 

D £ 


dn 

ft yj 


nR? 

U O £. 


BYTE 


fin 
o u 


fiR 


fi"? 
D j 


dn 

ft u 


U J j 


. BYTE 


fin 

q yj 


fill 


fid 
D ft 


dn 

ft u , 


n Rd 

U 3 ft 


BYTE 


fin 


fiR 


fiR 
D 3 


dn 

ft u 


U J J 


BYTE 


fin 


fiR 
D 3 


fifi 
DO 


dn 

ft yj 


net 
U DO 


BYTE 


fin 

o yj 


fiR 


fi7 
D / 


dn 

ft u , 


n R7 

U O 1 


. BYTE 


60 


66 


60 


40 


nfin 


BYTE 


fin 

o yj 


fifi 

D 


fi i 

1 


dn 

t u ( 


nfii 

U D 1 


BYTE 


fin 

o u 


fifi 
D 


fi? 


dn • 

ft u ( 


nfi? 

U D Z 


• O 1 1 Ci 


fin 

o u 


fifi 
D O 


fi ~x 

D O 


d n i 
ft u , 


nfii 


BYTE 


fin 

o yj 


fifi 
D O 


fid 

Oft 


dn 

ft U ! 


n fid 

U Oft 


. BYTE 


60 


66 


65 


40 ; 


065 


. BYTE 


60 


66 


66 


40 • 


066 


.BYTE 


60 


66 


67 


40 ; 


067 


. BYTE 


60 


67 


60 


40 ; 


070 


. BYTE 


60 


67 


61 


40 ; 


07 1 


.BYTE 


60 


67 


62 


40 : 


72 


.DIlCi 


fin 


fi7 
Off 


fi"? 

DO, 


40 


073 


DVT 1 !? 
. OX 1 D 


fin 


fi7 
Off 


fid 
D ft , 


40 


074 


• D X 1 Ci 


fin 
o u , 


fi7 

D / , 


65 


40 ; 


075 


BVTT? 
■ DIlCi 


fin 

DU , 


fi7 
D / t 


fifi 

O D , 


40 


076 


, Ox Id 


fin 

DU r 


fi7 
D / , 


fi7 

D / , 


40 


077 


QVPIT 


fi 1 
Dl i 


fin 

DU , 


fin 

DU , 


40 


100 




fi 1 


fin 

DU , 


fil 
D 1 , 


dn • 

ft u , 


101 


qvti? 

,DIl& 


fil 

Dl ; 


fin 

DU , 


fi? 
D £• i 


dn 


102 




fi 1 

Dl i 


fin 

DU , 


fil 
DO , 


dn 

ft \j , 


103 


tDIlu 


fil 
D 1 i 


fin 

D U f 


64 


40 ; 


104 


HVTT? 
. Dl 1 Ci 


fi 1 
D 1 | 


fin 

DU | 


fiR 


40 


105 


• Dl J. Ci 


fil 
D 1 


fin 

DU f 


fifi 

D D | 


40 


106 


QVTTT 
tOllu 


fi 1 
D 1 


fin 

DU , 


fi7 


40 


107 


ovmp 


fil 
D 1 


fil 

D 1 


fin 

D VJ 


40 


110 


. Dl i Ci 


fi 1 
D 1 


fil 
D 1 


fi 1 
D 1 


dn 

ft u , 


111 


HVT17 


fi 1 
1 


fil 
D 1 


fi? 
D £ 


dn 

ft yj t 


112 


. O X 1 Ci 


fil 
D 1 


fil 
D 1 


fi - } 


40 


113 


. a x 1 Ci 


fi 1 
D 1 


fil 
D 1 


fid 


dn 

ft U i 


114 


. OX 1 Ci 


fi 1 
D 1 


fi 1 
1 


fiR 
D 3 


dn 

ft U i 


115 


. 01 i Ci 


fi 1 
D 1 


fil 
O 1 


fifi 
DD 


dn 

ft U 


116 


. Dl i Ci 


fi 1 
D 1 


fi 1 
D 1 


fi7 
D / 


dn 
ft \j 


117 


uvpi? 

. D I 1 Ci 


fi 1 
D 1 


fi? 
D £ 


fin 
ou 


dn 

ft yj 


120 


. O X 1 Ci 


fi 1 
D 1 


fi? 
D^ 


fil 

D 1 


40 


121 


• O X 1 Ci 


fil 
D 1 


fi? 
D c. 


62 


40 


122 


. O X 1 Ci 


fil 
D 1 


fi? 


fi^ 

r DJ 


40 


123 


. OX 1 Ci 


fil 
D 1 


fi? 


fid 

r D fx 


40 


124 


DVT1T 
. B X 1 Ci 


fil 
D 1 


fi? 
f D £ 


fiR 


40 


125 


, OI ICi 


fil 
D 1 


fi? 
r D£ 


fifi 

, DD 


40 


126 


. OX 1 Ci 


fil 
D 1 


fi? 


fi7 


dn 

, ft u 


127 


• O X 1 Ci 


fil 
D 1 


fi^ 
r U J 


60 


40 


130 


■ OI 1L 


fil 
D 1 


fi"} 

^ DJ 


fil 

1 D 1 


40 


: 131 


. BYTE 


61 


63 


,62 


, 40 


1 132 


.BYTE 


61 


'63 


^63 


',i0 


; 133 


.BYTE 


61 


,63 


,64 


,40 


;134 


. BYTE 


61 


,63 


,65 


,40 


;13 5 


.BYTE 


61 


,63 


,66 


,40 


;136 


. BYTE 


61 


,63 


,67 


,40 


; 13 7 
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. BYTE 


61 


64 


,60 


40 


140 


.BYTE 


61 


64 


61 


40 


141 


.BYTE 


61 


64 


62 


40 


142 


.BYTE 


61 


64 


63 


40 


143 


.BYTE 


61 


64 


64 


40 


144 


.BYTE 


61 


64 


65 


40 


145 


.BYTE 


61 


64 


66 


40 


146 


.BYTE 


61 


64 


67 


40 


147 


.BYTE 


61 


65 


60 


40 


150 


.BYTE 


61 


65 


61 


40 


151 


.BYTE 


61 


65 


62 


40 


152 


.BYTE 


61 


65 


63 


40 


153 


.BYTE 


61 


65 


64 


40 


154 


.BYTE 


61 


65 


65 


40 


155 


.BYTE 


61 


65 


66 


40 


156 


.BYTE 


61 


65 


67 


40 


157 


.BYTE 


61 


66 


60 


40 


160 


.BYTE 


61 


66 


61 


40 


161 


.BYTE 


61 


66 


62 


40 


162 


.BYTE 


61 


66 


63 


40 


163 


. 3YTE 


61 


66 


64 


40 


164 


. BYTE 


61 


66 


65 


40 


165 


. 3YTE 


6 i 


66 


66 


40 


166 


; 3YTE 


61 


66 


67 


40 


16~ 


.BYTE 


61 


67 


,60 


40 


170 


.BYTE 


61 


67 


61 


40 


•171 


.BYTE 


61 


67 


62 


40 


172 


.BYTE 


61 


67 


63 


40 


173 


.BYTE 


61 


67 


64 


40 


174 


.BYTE 


61 


67 


65 


40 


175 


.BYTE 


61 


67 


66 


40 


176 


.BYTE 


61 


67 


67 


40 


177 


. BYTE 


62 


60 


60 


40 


200 


. BYTE 


62 


60 


61 


40 


201 


.BYTE 


62 


60 


62 


40 


202 


.BYTE 


62 


60 


63 


40 


203 


.BYTE 


62 


60 


64 


40 


204 


.BYTE 


62 


60 


65 


40 


205 


.BYTE 


62 


60 


66 


40 


206 


.BYTE 


62 


60 


67 


40 


207 


.BYTE 


62 


61 


60 


40 


210 


.BYTE 


62 


61 


61 


40 


211 


.BYTE 


62 


61 


62 


40 


212 


.BYTE 


62 


61 


63 


40 


213 


.BYTE 


62 


61 


64 


40 


214 


.BYTE 


62 


61 


65 


40 


215 


.BYTE 


62 


61 


66 


40 


216 


.BYTE 


62 


61 


67 


40 


217 


.BYTE 


62 


62 


60 


40 


220 


.BYTE 


62 


62 


61 


40 


221 


.BYTE 


62 


62 


62 


40 


222 


.BYTE 


62 


62 


63 


40 


223 


.BYTE 


62 


62 


64 


40 


224 


.BYTE 


62 


62 


65 


40 


225 


.BYTE 


62 


62 


66 


40 


226 


.BYTE 


62 


62 


67 


40 


227 


.BYTE 


62 


63 


60 


40 


230 


.BYTE 


62 


63 


61 


40 


231 


.BYTE 


62 


63 


62 


40 


232 


.BYTE 


62 


63 


63 


40 


233 


.BYTE 


62 


63 


64 


40 


234 
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.BYTE 


62 


63 


65 


40 


235 


.BYTE 


62 


63 


66 


40 


236 


.BYTE 


62 


63 


67 


40 


237 


.BYTE 


62 


64 


60 


40 


240 


.BYTE 


62 


64 


61 


40 


241 


.BYTE 


62 


64 


62 


40 


242 


.BYTE 


62 


64 


63 


40 


243 


.BYTE 


62 


64 


64 


40 


244 


.BYTE 


62 


64 


65 


40 


245 


.BYTE 


62 


64 


66 


40 


246 


.BYTE 


62 


64 


67 


40 


247 


.BYTE 


62 


65 


60 


40 


250 


.BYTE 


62 


65 


61 


40 


251 


.BYTE 


62 


65 


62 


40 


252 


.BYTE 


62 


65 


63 


40 


253 


.BYTE 


62 


65 


64 


40 


254 


.BYTE 


62 


65 


65 


40 


255 


.BYTE 


62 


65 


66 


40 


256 


.BYTE 


62 


65 


67 


40 


257 


.BYTE 


62 


66 


60 


40 


260 


. BYTE 


62 


66 


61 


40 


261 


. BYTE 


62 


66 


62 


40 


262 


. 3YTE 


6 2 


66 


63 


40 


263 


. BYTE 


62 


66 


64 


40 


264 


.BYTE 


62 


66 


65 


40 


265 


.BYTE 


62 


66 


66 


40 


266 


.BYTE 


62 


66 


67 


40 


267 


.BYTE 


62 


67 


60 


40 


270 


.BYTE 


62 


67 


61 


40 


271 


.BYTE 


62 


67 


62 


40 


272 


.BYTE 


62 


67 


63 


40 


273 


.BYTE 


62 


67 


64 


40 


274 


.BYTE 


62 


67 


65 


40 


275 


.BYTE 


62 


67 


66 


40 


276 


.BYTE 


62 


67 


67 


40 


277 


.BYTE 


63 


60 


60 


40 


300 


.BYTE 


63 


60 


61 


40 


301 


.BYTE 


63 


60 


62 


40 


302 


.BYTE 


63 


60 


63 


40 


303 


.BYTE 


63 


60 


64 


40 


304 


.BYTE 


63 


60 


65 


40 


305 


.BYTE 


63 


60 


66 


40 


306 


• BYTE 


63 


60 


67 


40 


307 


. BYTE' 


63 


61 


60 


40 


310 


.BYTE 


63 


61 


61 


40 


311 


.BYTE 


63 


61 


62 


40 


312 


.BYTE 


63 


61 


63 


40 


313 


.BYTE 


63 


61 


64 


40 


314 


.BYTE 


63 


61 


65 


40 


315 


.BYTE 


63 


61 


66 


40 


316 


.BYTE 


63 


61 


67 


40 


317 


.BYTE 


63 


,62 


60 


40 


320 


.BYTE 


63 


,62 


61 


40 


321 


.BYTE 


63 


,62 


62 


40 


322 


.BYTE 


63 


,62 


63 


,40 


■323 


.BYTE 


63 


,62 


64 


,40 


• 324 


.BYTE 


63 


,62 


65 


,40 


■ 325 


.BYTE 


63 


,62 


66 


,40 


•326 


.BYTE 


63 


,62 


,67 


,40 


•327 


.BYTE 


63 


,63 


,60 


,40 


•330 


.BYTE 


63 


,63 


,61 


,40 


;331 



4-54 



(continued on next page) 
DECnet-RSX Programmer's Reference Manual 



.BYTE 


63 


63 


.BYTE 


63 


63 


.BYTE 


63 


63 


.BYTE 


63 


63 


.BYTE 


63 


63 


.BYTE 


63 


63 


.BYTE 


63 


64 


.BYTE 


63 


64 


.BYTE 


63 


64 


.BYTE 


63 


64 


.BYTE 


63 


64 


.BYTE 


63 


64 


.BYTE 


63 


64 


.BYTE 


63 


64 


.BYTE 


63 


65 


.BYTE 


63 


65 


.BYTE 


63 


65 


.BYTE 


63 


65 


.BYTE 


63 


65 


.BYTE 


63 


65 


.BYTE 


63 


65 


. BYTE 


63 


65 


. BYTE 


63 


66 


. 3YTE 


63 


66 


.BYTE 


63 


66 


.BYTE 


63 


66 


.BYTE 


63 


66 


.BYTE 


63 


66 


.BYTE 


63 


66 


.BYTE 


63 


66 


.BYTE 


63 


67 


.BYTE 


63 


67 


.BYTE 


63 


67 


. ox 1 Cj 


D J 


o / 


.BYTE 


63 


67 


.BYTE 


63 


67 


.BYTE 


63 


67 


.BYTE 


63 


67 


. END 


START 



62 


40 


332 


63 


40 


333 


64 


40 


334 


65 


40 


335 


66 


40 


336 


67 


40 


337 


60 


40 


340 


61 


40 


341 


62 


40 


342 


63 


40 


343 


64 


40 


344 


65 


40 


345 


66 


40 


346 


67 


40 


347 


60 


40 


350 


61 


40 


351 


62 


40 


352 


63 


40 


353 


64 


40 


354 


65 


40 


355 


66 


40 


356 


67 


40 


357 


60 


40 


360 


61 


40 


361 


62 


40 


■362 


63 


40 


•363 


64 


40 


■364 


65 


40 


•365 


66 


40 


366 


67 


40 


367 


60 


40 


•370 


61 


40 


•371 


62 


40 


•372 


63 


40 


373 


64 


40 


374 


65 


40 


•375 


66 


40 


•376 


67 


40 


•377 



DLX: Direct Line Access Controller 



4-55 



A 

Disconnect or Reject Reason Codes 



The following list contains the error reasons codes available at the logical link user 
interface. These codes can be returned after either of the following events occurs: 

• A connect request was rejected by the network (IE.NRJ); see Section 2.3.5. 

• A connected logical link was aborted by the network (NT. ABO); see Section 2.3.2. 

The symbols in column 1 are defined in the macro NSSYM$. NSSYM$ is located in 
NETLIB.MLB (moved to LB: [1,1] during network generation). The events in column 
5 indicate the condition that occurred. C refers to a connect request and A refers to a 
network abort. 

Symbol Decimal Octal 

Name Value Value Standard Message/Explanation Event 

NE$RES 1 1 Insufficient network resources C 

The logical link could not be con- 
nected because either the local or the 
remote node had insufficient network 
resources (for example, insufficient 
logical links, remote node counters, or 
dynamic storage region (DSR) on RSX 
systems). 

NE$NOD 2 2 Unrecognized node name C 

The logical link could not be con- 
nected because the destination node 
name did not correspond to any known 
node address. 

(continued on next page) 
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Symbol Decimal Octal 

Name Value Value Standard Message/Explanation Event 



NE$NSR 



NE$UOB 



NE$FMT 



NE$MLB 



NE$ABM 8 



NE$NNF 10 



10 



12 



NE$NSL 11 



13 



Remote node shutting down 

The logical link could not be con- 
nected because the network on the re- 
mote node was in the process of shut- 
ting down and would accept no more 
logical link connections. 

Unrecognized object 

The logical link could not be con- 
nected because the object number or 
name specified did not exist at the re- 
mote node. 

Invalid object name format 

The logical link could not be con- 
nected because the node did not un- 
derstand the object name format. 

Object too busy 

The logical link could not be con- 
nected because the remote object was 
too busy handling other logical links. 

Abort by network management 

The logical link has been aborted by 
an operator or a program using net- 
work management. 

Invalid node name format 

The logical link could not be con- 
nected because the remote node name 
format was invalid. For example, the 
name contained illegal characters or 
was too long. 

Local node shutting down 

The logical link could not be con- 
nected because the network on the lo- 
cal node was in the process of shutting 
down. 



(continued on next page) 
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Symbol Decimal Octal 
Name Value Value 



Standard Message/Explanation 



Event 



NE$ACC 34 



42 



NE$ABO 38 



46 



NE$ABO 38 



NE$COM 39 



46 



47 



Access control rejected 

The logical link could not be con- 
nected because the remote node or ob- 
ject could not understand or would not 
accept the access control information. 

No response from object 

The logical link could not be con- 
nected because the object did not re- 
spond. For example, the object re- 
sponded too slowly or terminated ab- 
normally. 

Remote node or object failed 

The connected logical link was aborted 
because the remote node or the object 
terminated abnormally. 

Node unreachable 

Either the logical link could not be 
connected or the connected logical link 
was aborted because no path existed 
to the remote node. 



C/A 
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B 

Object Types 



The object type code values that have been defined by Digital are listed below, 
expressed as octal and decimal byte values. Digital reserves the right to add object 
types and to make changes to the descriptor formats used by the object types. At 
present, a descriptor format of 1 indicates a user process (object type 000). All other 
listed object types have a descriptor format of 0, requiring definition by the object 
type codes given in the first two columns below. 

Object Type 

Octal Decimal Process Type 



000 


000 


General task, user process 


001 


001 


File Access Listener (FAL/DAP) Version 1 


002 


002 


Unit record services (URDS) 


003 


003 


Application terminal services (ATS) 


004 


004 


Command terminal services (CTS) 


005 


005 


RSX-11M Remote Task Control utility (TCL) Version 1 


006 


006 


Operator services interface 


007 


007 


Node resource manager 


010 


008 


IBM 3270-BSC Gateway 


011 


009 


IBM 2780-BSC Gateway 


012 


010 


IBM 3790-SDLC Gateway 


013 


011 


TPS application 


014 


012 


RT-11 DIBOL application 


015 


013 


TOPS-20 terminal handler 



(continued on next page) 



B-1 



Object Type 
Octal Decimal 



Process Type 



016 


014 


TOPS-90 rpmotp (snnnlpr 


017 


015 


RSX-11M Rpmotp Ta<?k Control utilitv (TCJA Vpr<?ion 2 


020 


016 


TLK utilitv (XSNi 


021 


017 


T^ilp A f*i"»PGC T .icfortoi 1 (TP A T ./Ti AT^ \7pTcirvn A onH 1 afar 
1 lie /TCCCOO JjloUCllCl \x r\xj/ XJr\xT ) VG1&1LU1 *± dllll xdl/Cl 


022 


018 


AOA 1 lu XxUoL IjUdUcl Utility yixJuLJ ) 


023 


01 Q 


Network Information and Control Exchange (NICE) 


094 


090 


noio/ Hi media transier program ^iNiziivyi^i ) 


025 


021 


RSTS/R-tn PQTS/R npfwnrlr pnmmfiTiH fprminn] hsinrllpr 
XvO J. O/ X-J-tU-XvO X O/l-J IlcbWUlA. CUlIlllldllU. IvtJI lllllldi Ild.IlU.lt! I 




099 


iviaii iibcencr \^j^v>nei>udseu electronic man systems 


027 


023 


^ptwnrlr pnm m £*nrl tpt*rnin£il VifiTirllpr fVinct cirlpi 
l'ictwuiR lA^xixnidinj. i/Cimindi lidiidicx oiuic^ 


030 


024 


"Wptwm*lr f*nm m ann t ptto ins*! VinnHl pi* ( t pttyi iti£)I cinPl 

livtWUXlV ^UlllllldllLl l>Vx Illllldl lldlllllCi \ l/Cl lllllldl &1LIC ) 


031 


025 


T ■nnnn a m i wfvr ( IvTTT? 1 
X^KJKJ^J L/dUJV 11111 1 Ul yxvxxxx/ 


032 


026 


Event receiver (EVR) 


033 


027 


VA^C/VlvTS TiPTdnTifll TYipciQflP'p utilitv 

v nix/ v xvxkj L/c-xovyxxcix xxxcsoag^ vxvxxxvy 


034 


028 


J? XXc lXdXXolcX OJJUUXcX V* ^ / 


035 


029 


PHONF, ntilitv 

-L X J. V-/ 1 N JJJ lll/XXXl/jr 


036 


030 


XJXsLXXUUUcU Udtd XXXcUldgCXXXcXXl/ Xal/XXXty VXJXj'iVXr y 


037 


031 


X.25 Gateway access 


040-076 


032-062 


Reserved for DECnet use 


077 


063 


DECnet test tool (DTR) 


100-177 


064-127 


Reserved for DECnet use 


200-377 


128-255 


Reserved for customer use 
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c 

Summary of Remote File Access Error/Completion 

Codes 



C.1 I/O Status Block Error Returns 

Each remote file access subroutine returns a 2-word I/O status block. The contents of 
the second word depend on the contents of the first word. 

Table C-1 describes each code that can be returned in the first word of the status 
block. The description of the code tells you where to look up the description of the 
value returned in the second word. 



Table C-1 : First Word I/O Status Block Error Codes 



Error Code 

177777 (-1) 



177776 (-2) 



Description 

CHANNEL ALREADY ACTIVE 

An attempt has been made to open a file on an active channel. 
Either another channel must be used or the active channel must be 
released via a close prior to reusing it. 

The second word of the I/O status block is not applicable. 

CHANNEL NOT ACTIVE 

A file operation request has been made on an inactive channel. 
Either a file open has not been issued on this channel or the net- 
work link for this channel has been lost. 



The second word of the I/O status block is not applicable. 
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Table C-1 (cont.): First Word I/O Status Block Error Codes 



Error Code 

177775 (-3) 



177774 (-4) 



177773 (-5) 



177772 (-6) 



177771 (-7) 



177770 (-8) 



Description 

DATA ACCESS PROTOCOL ERROR 

An error has been detected by the remote file system or by the 
remote server task. The error is then returned to the user by DAP. 

The second word of the I/O status block contains the file access 
error code. Look up this code in Table C-3. 

NSP ERROR (see Table C-2) 

The Data Access Protocol (DAP) utilities depend on Network Ser- 
vices Protocol (NSP) as a vehicle for accessing remote files. This 
code indicates that a problem has been encountered at the NSP 
level. 

The low-order byte of the second word of the I/O status block 
contains one of the NSP error codes listed in Table C-2. If this 
error is network rejection (-7), the high-order byte of the second 
word of the I/O status block contains the reject reason code (see 
Appendix A). 

INVALID ATTRIBUTES 

An invalid character has been found in the attributes array (ichar) 
of an open command. 

DATA OVERRUN 

A message or block of messages was received that did not fit into 
the user-specified buffer. 

The second word of the I/O status block contains the total number 
of bytes read. 

TASKS OUT OF SYNC 

The requesting task and its server (FAL) have lost Data Access 
Protocol (DAP) message synchronization. This indicates a serious 
internal software problem that should be reported to your system 
manager. 

The second word of the I/O status block is not applicable. 
INVALID DAP CHANNEL (LUN) 

DAP channel numbers must fall in the range of 1 to 255. A 
channel or a channel value greater than 255 is invalid. 

The second word of the I/O status block is not applicable. 

(continued on next page) 
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Table C-1 (cont.): First Word I/O Status Block Error Codes 



Error Code Description 

177767 (-9) BUFFER ALLOCATION ERROR FOR DAP CHANNELS 

There is no more buffer space available for the DAP channel con- 
trol blocks. To extend the buffer size, the FORTRAN program 
must be rebuilt, increasing the size of $FSR1 in the task build. 

The second word of the I/O status block is not applicable. 

177766 (-10.) DIRECTIVE ERROR 

Directive error from the executive. 

The second word of the I/O status block contains the DSW value. 

177765 (-11.) ILLEGAL REQUEST 

An illegal request was made (for example, an attempt to read from 
a file that was open for write). 

The second word of the I/O status block is not applicable. 

Table C-2 contains the NSP error codes that pertain to the NSP ERROR in Table 
C-1 (177774). NSP error codes occupy the low-order byte of the second word of the I/O 
status block. With the exception of the network rejection (-7), the high-order byte is 
undefined. 



Table C-2: NSP Error Codes 



Error Code Description 



Required system resources are not available. 

A request was issued for a LUN on which there is no established logical link. 

The link was disconnected with the request outstanding. 

The data message to be received was truncated because the receive buffer was 
too small. 

An argument specified in the call was incorrect. 
No network data was found in the user's mailbox. 

The network (NSP) rejected an attempted connect. The high-order byte con- 
tains the reject reason code (see Appendix A). 
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Table C-2 (cont.): NSP Error Codes 



Error Code Description 

-8 A logical link has already been established on the LUN to which the user 

attempted to connect. 

-9 The issuing task is not part of the network. OPNNT was never called. 

-10 The user is attempting to access the network for a second time. 

-11 A transmission of an interrupt message was attempted before the last one had 

finished. 

-12 A connect reject was issued by the user task to which the connection was 

attempted. 

-13 A buffer is either outside the user address space or is not word aligned. 

-14 The user is attempting to issue a GNDNTfW] when one is already pending. 



C.2 Data Access Protocol (DAP) Error Messages 

The DAP status code is used to return status from the remote file system or from the 
operation of the cooperating process using DAP. The 2-byte status field (16 bits) 
occupies the second word of the I/O status block and is divided into two fields: 

• Maccode (bits 12-15): Contains the error type code (see Table C-3 in Section 

C.2.1) 

• Miccode (bits 0-11): Contains the specified error reason code (see Tables C-4, 

C-5, and C-6, depending on error type, as described in 
Section C.2. 2) 

C.2.1 Maccode Field 

The maccode field is located in the high-order byte of the second word in an I/O status 
block. The value returned in the maccode field describes the functional type of the 
error that has occurred. The specific reason for the error is given in the miccode field 
(the low-order byte of the same word that contains the maccode field). Miccode 
values correlating to each maccode value listed in Table C-3 are found in the table 
referenced in the last column of Table C-3. 
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Table C-3: DAP Maccode Field Values 



Field 
Value 



Error 
Type 



Meaning 



Miccode 
Table 




1 
2 

3 
4 

5 

6 

7 

10 

11 

12 

13-15 
16-17 



Pending 

Successful 

Unsupported 

Reserved 
File open 

Transfer error 

Transfer 
warning 

Access 
termination 

Format 
Invalid 

Sync 

Reserved 

User-defined 
status maccodes 



The operation is in progress. C-5 

Returns information that indicates success. C-5 

This implementation of DAP does not sup- C-4 
port specified request. 



Errors that occur before a file is successfully C-5 
opened. 

Errors that occur after a file is opened and C-5 
before it is closed. 

For operations on open files, indicates that C-5 
the operation completed, but not with com- 
plete success. 

Errors associated with terminating access to C-5 
a file. 

Error in parsing a message. Format is not C-4 
correct. 

Field of message is invalid (that is, bits that C-4 
are meant to be mutually exclusive are set, 
an undefined bit is set, a field value is out of 
range, or an illegal string is in a field). 

DAP message received out of synchroniza- C-6 
tion. 



C.2.2 Miccode Field 

The miccode field is located in the low-order byte of the second word in an I/O status 
block. The value returned in this field identifies the specific reason for the error type 
defined in the maccode field (see Section C.2.1). Miccode field values are defined in 
three different tables, each table associated with certain maccode values, as outlined 
below: 

• Table C-4: For use with maccode values 2, 10, 11 

• Table C-5: For use with maccode values 0, 1, 4, 5, 6, 7 

• Table C-6: For use with maccode value 12 
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Table C-4 follows. The DAP message type number (column 1) is specified in bits 
6-11, and the DAP message field number (column 2) is specified in bits 0-5. The field 
where the error is located is described in the third column. 



Table C-4: DAP Miccode Values for Use with Maccode Values of 2, 10, and 11 



Type 
Number 
(bits 6-11) 



Field 
Number 
(bits 0-5) 



Miscellaneous message errors 
00 00 
10 

Configuration message errors 



01 



00 
10 
11 
12 
13 
14 
20 
21 
22 
23 
24 
25 
26 
27 
30 



Field Description 

Unspecified DAP message error 
DAP message type field (TYPE) error 

Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

BITCNT field (BITCNT) 

Buffer size field (BUFSIZ) 

Operating system type field (OSTYPE) 

File system type field (FILESYS) 

DAP version number (VERNUM) 

ECO version number field (ECONUM) 

USER protocol version number field (USRNUM) 

DEC software release number field (DECVER) 

User software release number field (USRVER) 

System capabilities field (SYSCAP) 



(continued on next page) 
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Table C-4 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 10, 
and 11 



Type Field 
Number Number 

(bits 6-11) (bits 0-5) Field Description 

Attributes message errors 



00 


Unknown field 


10 


DAP message flags field (FLAGS) 


11 


Data stream identification (STREAMID) 


12 


Length field (LENGTH) 


13 


Length extension field (LEN 256) 


14 


Bit count field (BITCNT) 


20 


Attributes menu field (ATTMENU) 


21 


Data type field (DATATYPE) 


22 


File organization field (ORG) 


23 


Record format field (RFM) 


24 


Record attributes field (RAT) 


25 


Block size field (BLS) 


26 


Maximum record size field (MRS) 


27 


Allocation quantity field (ALQ) 


30 


Bucket size field (BKS) 


31 


Fixed control area size field (FSZ) 


32 


Maximum record number field (MRN) 


33 


Run-time system field (RUNSYS) 


34 


Default extension quantity field (DEQ) 


35 


File options field (FOP) 


36 


Byte size field (BSZ) 
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Table C-4 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 10, 
and 11 



Type 
Number 
(bits 6-11) 



Field 
Number 
(bits 0-5) 

37 
40 
41 
42 
43 
44 
45 



Access message errors 



03 



00 
10 
11 
12 
13 
14 
20 
21 
22 
23 
24 
25 
26 



Field Description 

Device characteristics field (DEV) 

Spooling device characteristics field (SDC); reserved 

Longest record length field (LRL) 

Highest virtual block allocated field (HBK) 

End-of-file block field (EBK) 

First free byte field (FFB) 

Starting LBN for contiguous file field (SBN) 

Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

Access function field (ACCFUNC) 

Access options field (ACCOPT) 

File specification field (FILESPEC) 

File access field (FAC) 

File-sharing field (SHR) 

Display attributes request field (DISPLAY) 

File password field (PASSWORD) 



(continued on next page) 
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Table C-4 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 10, 
and 11 



Type Field 
Number Number 
(bits 6-11) (bits 0-5) 


Field Description 


Control message errors 




04 00 


Unknown field 


10 


DAP message flags field (FLAGS) 


11 


Data stream identification field (STREAMID) 


12 


Length field (LENGTH) 


13 


Length extension field (LEN256) 


14 


Bit count field (BITCNT) 


20 


Control function field (CTLFUNC) 


21 


Control menu field (CTLMENU) 


22 


Record access field (RAC) 


23 


Key field (KEY) 


24 


Key of reference field (KRF) 


25 


Record options field (ROP) 


26 


Hash code field (HSH); reserved for future use 


27 


Display attributes request field (DISPLAY) 


30 


Block count (BLKCNT) 


Continue message errors 




05 00 


Unknown field 


10 


DAP message flags field (FLAGS) 


11 


Data stream identification field (STREAMID) 


12 


Length field (LENGTH) 


13 


Length extension field (LEN256) 


14 


Bit count field (BITCNT) 


20 


Continue transfer function field (CONFUNC) 
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Table C-4 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 10, 
and 11 



Type 
Number 
(bits 6-11) 



Field 
Number 
(bits 0-5) 



Field Description 



Acknowledge message errors 
06 00 

10 

11 

12 

13 

14 

15 

Access complete message errors 



07 



Data message errors 
10 



00 
10 
11 
12 
13 
14 
20 
21 
22 

00 
10 
11 
12 
13 
14 
20 
21 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

System-specific field (SYSPEC) 

Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

Access complete function field (CMPFUNC) 

File options field (FOP) 

Checksum field (CHECK) 

Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

Record number field (RECNUM) 

File data field (FILEDATA) 



(continued on next page) 
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Table C-4 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 10, 
and 11 



Type 
Number 
(bits 6-11) 



Field 
Number 
(bits 0-5) 



Status message errors 
11 00 
10 
11 
12 
13 
14 
20 
21 
22 
23 
24 
25 

Key definition message errors 



12 



00 
10 
11 
12 
13 
14 
20 
21 
22 



Field Description 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

Macro status code field (MACCODE) 

Micro status code field (MICCODE) 

Record file address field (RFA) 

Record number field (RECNUM) 

Secondary status field (STV) 

Secondary status text (STX) 

Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

Key definition menu field (KEYMENU) 

Key option flags field (FLG) 

Data bucket fill quantity field (DFL) 

(continued on next page) 
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Table C-4 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 10, 
and 11 

Type Field 
Number Number 

(bits 6-11) (bits 0-5) Field Description 



23 Index bucket fill quantity field (IFL) 

24 Key segment repeat count field (SEGCNT) 

25 Key segment position field (POS) 

26 Key segment size field (SIZ) 

27 Key of reference field (REF) 

30 Key name field (KNM) 

31 Null key character field (NUL) 

32 Index area number field (IAN) 

33 Lowest level area number field (LAN) 

34 Data level area number field (DAN) 

35 Key data type field (DTP) 

36 Root VBN for this key field (RVB) 

37 Hash algorithm value field (HAL) 

40 First data bucket VBN field (DVB) 

41 Data bucket size field (DBS) 

42 Index bucket size field (IBS) 

43 Level of root bucket field (LVL) 

44 Total key size field (TKS) 

45 Minimum record size field (MRL) 
Allocation message errors 

13 00 Unknown field 

10 DAP message flags field (FLAGS) 

11 Data stream identification field (STREAMID) 

12 Length field (LENGTH) 

(continued on next page) 
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Table C-4 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 10, 

and 11 
Type Field 
Number Number 

(bits 6-11) (bits 0-5) Field Description 



13 Length extension field (LEN256) 

14 Bit count field (BITCNT) 

20 Allocation menu field (ALLMENU) 

21 Relative volume number field (VOL) 

22 Alignment options field (ALN) 

23 Allocation options field (AOP) 

24 Starting location field (LOC) 

25 Related file identification field (RFI) 

26 Allocation quantity field (ALQ) 

27 Area identification field (AID) 

30 Bucket size field (BKZ) 

31 Default extension quantity field (DEQ) 
Summary message errors 

14 00 Unknown field 

10 DAP message flags field (FLAGS) 

11 Data stream identification field (STREAMID) 

12 Length field (LENGTH) 

13 Length extension field (LEN256) 

14 Bit count field (BITCNT) 

20 Summary menu field (SUMENU) 

21 Number of keys field (NOK) 

22 Number of areas field (NOA) 

23 Number of record descriptors field (NOR) 

24 Prologue version number (PVN) 
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Table C-4 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 10, 
and 11 

Type Field 
Number Number 

(bits 6-11) (bits 0-5) Field Description 



Date and time message errors 
15 00 
10 
11 
12 
13 
14 
20 
21 
22 
23 
24 
25 
26 
27 

Protection message errors 



16 



00 
10 
11 
12 
13 
14 
20 
21 
22 
23 
24 
25 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

Date and time menu field (DATMENU) 

Creation date and time field (CDT) 

Last update date and time field (RDT) 

Deletion date and time field (EDT) 

Revision number field (RVN) 

Backup date and time field (BDT) 

Physical creation date and time field (PDT) 

Accessed date and time field (ADT) 

Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

Protection menu field (PROTMENU) 

File owner field (OWNER) 

System protection field (PROTSYS) 

Owner protection field (PROTOWN) 

Group protection field (PROTGRP) 

World protection field (PROWLD) 

(continued on next page) 
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Table C-4 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 10, 
and 11 

Type Field 
Number Number 

(bits 6-11) (bits 0-5) Field Description 



Name message errors 



00 


Unknown field 


10 


DAP message flags field (FLAGS) 


11 


Data stream identification field (STREAMID) 


12 


Length field (LENGTH) 


13 


Length extension field (LEN256) 


14 


Bit count field (BITCNT) 


20 


Name type field (NAMETYPE) 


21 


Name field (NAMESPEC) 



Access control list message errors (reserved for future use) 



00 


Unknown field 


10 


DAP message flags field (FLAGS) 


11 


Data stream identification field (STREAMID) 


12 


Length field (LENGTH) 


13 


Length extension field (LEN256) 


14 


Bit count field (BITCNT) 


15 


System-specific field (SYSPEC) 


20 


Access control list repeat count field (ACLCNT) 


21 


Access control list entry field (ACL) 



Table C-5 follows. The error code number (column 1) is contained in bits 0-11. 
Symbolic status codes (column 2, when shown) refer to the corresponding RMS or 
FCS status codes. They are included here for ease of reference only, as they have no 
meaning for DAP. 
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Table C-5: DAP Miccode Values for Use with Maccode Values 0,1,4, 5, 6, 7 



Corresponding 

Error Code Symbolic 

(bits 0-11) Status Code Error Description 

Unspecified error 

1 ER$ABO Operation aborted 

2 £R$ACC Fll-ACP could not access file 

3 ER$ACT File activity precludes operation 

4 ER$AID Bad area ID 

5 ER$ALN Alignment options error 

6 ER$ALQ Allocation quantity too large or value 

7 ER$ANI Not ANSI D format 

10 ER$AOP Allocation options error 

11 ER$AST Invalid (that is, synchronous) operation at AST 

level 

12 ER$ATR Attribute read error 

13 ER$ATW Attribute write error 

14 ER$BKS Bucket size too large 

15 ER$BKZ Bucket size too large 

16 ER$BLN BLN length error 

17 ER$BOF Beginning of file detected 

20 ER$BPA Private pool address 

21 ER$BPS Private pool size 

22 ER$BUG Internal RMS error condition detected 

23 ER$CCR Cannot connect RAB 

24 ER$CHG $UPDATE changed a key without having attrib- 

ute of XB$CHG set 

25 ER$CHK Bucket format check-byte failure 

26 ER$CLS RSTS/E close function failed 

27 ER$COD Invalid or unsupported COD field 

30 ER$CRE Fll-ACP could not create file 

(STV = system error code) 

(continued on next page) 
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Table C-5 (cont.)-- DAP Miccode Values for Use with Maccode Values 0, 1 , 4, 5, 
6, 7 



Corresponding 

Error Code Symbolic 

(bits 0-11) Status Code Error Description 

31 ER$CUR No current record (operation not preceded by 

get/find) 

32 ER$DAC Fll-ACP deaccess error during close 

33 ER$DAN Data area number invalid 

34 ER$DEL RFA-accessed record was deleted 

35 ER$DEV Bad device, or inappropriate device type 

36 ER$DIR Error in directory name 

37 ER$DME Dynamic memory exhausted 

40 ER$DNF Directory not found 

41 ER$DNR Device not ready 

42 ER$DPE Device has positioning error 

43 ER$DTP DTP field invalid 

44 ER$DUP Duplicate key detected; XB$DUP not set 

45 ER$ENT Fll-ACP enter function failed 

46 ER$ENV Operation not selected in ORG$ macro 

47 ER$EOF End of file 

50 ER$ESS Expanded string area too short 

51 ER$EXP File expiration date not yet reached 

52 ER$EXT File extend failure 

53 ER$FAB Not a valid FAB (BID does not = FB$BID) 

54 ER$FAC Illegal FAC for record operation, or FB$PUT not 

set for create 

55 ER$FEX File already exists 

56 ER$FID Invalid file ID 

57 EP$FLG Invalid flag-bits combination 

60 ER$FLK File is locked by other user 

61 ER$FND Fll-ACP find function failed 

(continued on next page) 
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Table C-5 (cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 4, 5, 
6, 7 



Corresponding 

Error Code Symbolic 

(bits 0-11) Status Code Error Description 

62 ER$FNF File not found 

63 ER$FNM Error in file name 

64 ER$FOP Invalid file options 

65 ER$FUL Device/file full 

66 ER$IAN Index area number invalid 

67 ER$IFI Invalid IFI value or unopened file 

70 ER$IMX Maximum NUM (254) areas/key XABS exceeded 

71 ER$INI $INIT macro never issued 

72 ER$IOP Operation illegal or invalid for file organization 

73 ER$IRC Illegal record encountered (with sequential files 

only) 

74 ER$ISI Invalid ISI value on unconnected RAB 

75 ER$KBF Bad key buffer address (KBF = 0) 

76 ER$KEY Invalid key field (KEY = or negative) 

77 ER$KRF Invalid key of reference ($GET/$FIND) 

100 ER$KSZ Key size too large 

101 ER$LAN Lowest level index area number invalid 

102 ER$LBL Not ANSI-labeled tape 

103 ER$LBY Logical channel busy 

104 ER$LCH Logical channel number too large 

105 ER$LEX Logical extend error; prior extend still valid 

106 ER$LOC LOC field invalid 

107 ER$MAP Buffer-mapping error 

110 ER$MKD F11ACP could not mark file for deletion 

111 ER$MRN MRN value = negative or relative key > MRN 

112 ER$MRS MRS value = for fixed length records and/or rela- 

tive files 

(continued on next page) 
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Table C-5 (cont.): DAP Miccode Values for Use with Maccode Values 0,1,4, 5, 
6, 7 



Corresponding 
Error Code Symbolic 

(bits 0-11) Status Code Error Description 

113 ER$NAM NAM block address invalid (NAM = or is not 

accessible) 

114 ER$NEF Not positioned to EOF (with sequential files only) 

115 ER$NID Cannot allocate internal index descriptor 

116 ER$NPK Indexed file; no primary key defined 

117 ER$OPN RSTS/E open function failed 

120 ER$ORD XABs not in correct order 

121 ER$ORG Invalid file organization value 

122 ER$PLG Error in file's prologue (reconstruct file) 

123 ER$POS POS field invalid (POS > MRS; STV = XAB 

indicator) 

124 ER$PRM Bad file date field retrieved 

125 ER$PRV Privilege violation (OS denies access) 

126 ER$RAB Not a valid RAB (BID does not = RB$BID) 

127 ER$RAC Illegal RAC value 

130 ER$RAT Illegal record attributes 

131 ER$RBF Invalid record buffer address (either odd or not 

word aligned if BLK-IO) 

132 ER$RER File read error 

133 ER$REX Record already exists 

134 ER$RFA Bad RFA value (RFA=0) 

135 ER$RFM Invalid record format 

136 ER$RLK Target bucket locked by another stream 

137 ER$RMV Fll-ACP remove function failed 

140 ER$RNF Record not found 

141 ER$RNL Record not locked 

142 ER$ROP Invalid record options 

(continued on next page) 
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Table C-5: (cont.)'- DAP Miccode Values for Use with Maccode Values 0, 1, 4, 5, 



6, 7 

Corresponding 
Error Code Symbolic 

(bits 0-11) Status Code Error Description 

143 ER$RPL Error while reading prologue 

144 ER$RRV Invalid RRV record encountered 

145 ER$RSA RAB stream currently active 

146 ER$RSZ Bad record size (RSZ > MRS or NOT = MRS if 

fixed length records) 

147 ER$RTB Record too big for user's buffer 

150 ER$SEQ Primary key out of sequence (RAC = RB$SEQ for 

$PUT) 

151 ER$SHR SHR field invalid for file (cannot share sequential 

files) 

152 ER$SIZ SIZ field invalid 

153 ER$STK Stack too big for save area 

154 ER$SYS System directive error 

155 ER$TRE Index tree error 

156 ER$TYP Error in file type extension on FNS is too big 

157 ER$UBF Invalid user buffer address (0, odd, or not word 

aligned if BLK-IO) 

160 ER$USZ Invalid user buffer size (USZ=0) 

161 ER$VER Error in version number 

162 ER$VOL Invalid volume number 

163 ER$WER File write error (STV = system error code) 

164 ER$WLK Device is write locked 

165 ER$WPL Error while writing prologue 

166 ER$XAB Not a valid XAB (@XAB = odd; STV = XAB 

indicator) 

167 BUGDDI Default directory invalid 

170 CAA Cannot access argument list 

171 CCF Cannot close file 



(continued on next page) 
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Table C-5 (cont.): DAP Miccode Values for Use with Maccode Values 0, 1, 4, 5, 



6, 7 

Corresponding 

Error Code Symbolic 

(bits 0-11) Status Code Error Description 

172 CDA Cannot deliver AST 

173 CHN Channel assignment failure (STV = system error 

code) 

174 CNTRLO Terminal output ignored due to Etrl/O) 

175 CNTRLY Terminal input aborted due to mm 

176 DNA Default file name string address error 

177 DVI Invalid device ID field 

200 ESA Expanded string address error 

201 FNA File name string address error 

202 FSZ FSZ field invalid 

203 IAL Invalid argument list 

204 KFF Known file found 

205 LNE Logical name error 

206 NOD Node name error 

207 NORMAL Operation successful 

210 OK DUP Inserted record had duplicate key 

211 OK IDX Index update error occurred; record inserted 

212 OK RLK Record locked, but read anyway 

213 OK RRV Record inserted in primary is okay; may not be 

accessible by secondary keys or RFA 

214 CREATE File was created, but not opened 

215 PBF Bad prompt buffer address 

216 PNDING Asynchronous operation pending completion 

217 QUO Quoted string error 

220 RHB Record header buffer invalid 

221 RLF Invalid related file 

222 RSS Invalid resultant string size 

223 RST Invalid resultant string address 

(continued on next page) 
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Table C-5 (cont.): DAP Miccode Values for Use with Maccode Values 0, 1, 4, 5, 
6, 7 



Corresponding 

Error Code Symbolic 

(bits 0-11) Status Code Error Description 

224 SQO Operation not sequential 

225 SUC Operation successful 

226 SPRSED Created file superseded existing version 

227 SYN File name syntax error 

230 TMO Timeout period expired 

231 ER$BLK FB$BLK record attribute not supported 

232 ER$BSZ Bad byte size 

233 ER$CDR Cannot disconnect RAB 

234 ER$CGJ Cannot get JFN for file 

235 ER$COF Cannot open file 

236 ER$JFN Bad JFN value 

237 ER$PEF Cannot position to end of file 

240 ER$TRU Cannot truncate file 

241 ER$UDF File currently in an undefined state; access is de- 

nied 

242 ER$XCL File must be opened for exclusive access 

243 Directory full 

244 IE.HWR Handler not in system 

245 IE.FHE Fatal hardware error 

246 Attempt to write beyond EOF 

247 IE.ONP Hardware option not present 

250 IE.DNA Device not attached 

251 IE.DAA Device already attached 

252 IE.DUN Device not attachable 

253 IE.RSU Shareable resource in use 

254 IE.OVR Illegal overlay request 

(continued on next page) 
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Table C-5 (cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 4, 5, 
6, 7 



Error Code 
(bits 0-11) 


Corresponding 
Symbolic 
Status Code 


Error Description 


255 


IE.BCC 


Block check or CRC error 


256 


IE.NOD 


Caller's nodes exhausted 


257 


IE.IFU 


Index file full 


260 


IE.HFU 


File header full 


261 


IE.WAC 


Accessed for write 


262 


IE.CKS 


File header checksum failure 


263 


IE.WAT 


Attribute control list error 


264 


IE.ALN 


File already accessed on LUN 


265 


IE.BTF 


Bad tape format 


266 


IE. ILL 


Illegal operation on file descriptor block 


267 


IE.2DV 


Rename; two different devices 


270 


IE.FEX 


Rename; new file name already in use 


271 


IE.RNM 


Cannot rename old file system 


272 


IE.FOP 


File already open 


273 


IE.VER 


Parity error on device 


274 


IE.EOV 


End of volume detected 


275 


IE.DAO 


Data overrun 


276 


IE.BBE 


Bad block on device 


277 


IE.EOT 


End of tape detected 


300 


IE.NBF 


No buffer space for file 


301 


IE.NBK 


File exceeds allocated space; no blocks left 


302 


IE.NST 


Specified task not installed 


303 


IE.ULK 


Unlock error 


304 


IE.NLN 


No file accessed on LUN 



(continued on next page) 
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Table C-5 (cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 4, 5, 
6,7 



Corresponding 



Error Code Symbolic 

(bits 0-11) Status Code Error Description 

305 IE.SRE Send/receive failure 

306 SPL Spool or submit command file failure 

307 NMF No more files 

310 CRC DAP file transfer checksum error 

311 Quota exceeded 

312 BUGDAP Internal network error condition detected 

313 CNTRLC Terminal input aborted due to I5trl/0 

314 DFL Data bucket fill size > bucket size in XAB 

315 ESL Invalid expanded string length 

316 IBF Illegal bucket format 

317 IBK Bucket size of LAN does not = IAN in XAB 

320 IDX Index not initialized 

321 IFA Illegal file attributes (corrupt file header) 

322 IFL Index bucket fill size > bucket size in XAB 

323 KNM Key name buffer not readable or writeable in XAB 

324 KSI Index bucket will not hold two keys for key of ref- 

erence 

325 MBC Multibuffer count invalid (negative value) 

326 NET Network operation failed at remote node 

327 OK ALK Record is already locked 

330 OK DEL Deleted record successfully accessed 

331 OK LEVI Retrieved record exceeds specified key value 

332 OK_NOP Key XAB not filled in 

333 OK — RNF Nonexistent record successfully accessed 

334 PLV Unsupported prologue version 

335 REF Illegal key of reference in XAB 

(continued on next page) 
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Table C-5 (cont.): DAP Miccode Values for Use with Maccode Values 0,1,4, 5, 
6, 7 



Corresponding 
Error Code Symbolic 

(bits 0-11) Status Code Error Description 

336 RSL Invalid resultant string length 

337 RVU Error updating RRVs; some paths to data may be 

lost 

340 SEG Data types other than string limited to one seg- 

ment in XAB 

341 Reserved 

342 SUP Operation not supported over network 

343 WBE Error on write behind 

344 WLD Invalid wildcard operation 

345 WSF Working set full (cannot lock buffers in working 

set) 

346 Directory listing: error in reading volume set 

name, directory name, or file name 

347 Directory listing: error in reading file attributes 

350 Directory listing: protection violation in trying to 

read the volume set, directory, or file name 

351 Directory listing: protection violation in trying to 

read file attributes 

352 Directory listing: file attributes do not exist 

353 Directory listing: unable to recover directory list 

after continue transfer (skip) 

354 SNE Sharing not enabled 

355 SPE Sharing page count exceeded 

356 UPI UPI bit not set when sharing with BRO set 

357 ACS Error in access control string 

360 TNS Terminator not seen 

361 BES Bad escape sequence 

362 PES Partial escape sequence 

363 WCC Invalid wildcard context value 



(continued on next page) 
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Table C-5 (cont.): DAP Miccode Values for Use with Maccode Values 0,1,4, 5, 
6,7 



Corresponding 
Error Code Symbolic 

(bits 0-11) Status Code Error Description 

364 IDR Invalid directory rename operation 

365 STR User structure (FAB/RAB) became invalid during 

operation 

366 FTM Network file transfer mode precludes operation 
6000 User-defined errors to 7777 



Table C-6 follows. The message type number is contained in bits 0-11. 
Table C-6: DAP Miccode Values for Use with Maccode Value 12 



Type 
Number 

(bits 0-11) Message Type 

Unknown message type 

1 Configuration message 

2 Attributes message 

3 Access message 

4 Control message 

5 Continue transfer message 

6 Acknowledge message 

7 Access complete message 

10 Data message 

11 Status message 

12 Key definition attributes extension message 

13 Allocation attributes extension message 

14 Summary attributes extension message 

15 Date and time attributes extension message 

16 Protection attributes extension message 

17 Name message 

20 Access control list extended attributes message 
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D 

MACRO-11 Connect Block Offset and Code Definitions 



The following MACRO-11 offset and code definitions refer to connect block offsets 
used in network connects and accepts. 

♦TITLE NETDEF - DECNET USER INTERFACE DEFINITIONS 
♦MACRO NETDF$,L,B 



CRBDF$ 
L »B 

CNBDF$ 
L »B 

NSSYM* 



NETDF* f)< fY 
NETDF* 

NETDF$ 



5 REQUEST DESCRIPTOR BLOCK 
5 REQUEST PENDING BLOCK 
1 RETURN SYMBOLS 



♦ MCALL 
CRBDF$ 
♦ MCALL 
CNBDF* 
♦ MCALL 
N 3 3 Y M $ 

♦ MACRO 

♦ ENDM 

♦ ENDM 
5 + 

5 REQUEST DESCRIPTOR BLOCK OFFSET DEFINITIONS FOR CONNECTS. 



N.RND 



N ♦ ROT 



N ♦ RFM 



{ 




004 
S 



FORMAT 



(UNUSED) 



fo 1 

1.030 



(continued on next page) 
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FORMAT 1 



N.RDEC 



N ♦ RDE 



N.RIDC 



N . R I D 



N.RPSC 



N.RPS 



N.RACC 



N.RAC 



{ 
{ 
{ 



1 
012 
3 
032 
034 
052 
054 
056 
064 
06 G 
7 
106 



* =0 

N , RND : 'L 

N . RFM s 'L 
N ♦ ROT : 'L 



♦ MACRO 

♦ i i f n b 
♦ ASECT 

♦ BLKB 

. BLKB 
. BLKB 



CRBDF* >L ,B »LST 



N * RDEC : 'L ' 
N.RDE: 'L ' 

, = .-18. 
N.RGPs 'L ' 
N.RU3: 'L ' 
N.RNMCs 'L ' 
N.RNM: 'L' 



LST 

6 
1 
1 

BLKB 18. 



BLKW 1 
BLKB 16. 



♦ List 



BLKW 
BLKW 
BLKW 
BLKB 



1 
1 
1 

12. 



Destination 
Destination 
Destination 

Format 
U n u s e d 

Format 1 

Destination 

Destination 

Format 2 

Destination 

Destination 

Destination 

Destination 



n ode n a m e 
descriptor format 
object type 



process byte count 
process 



Sroup 
user 

name b/te count 
n am e 



(continued on next page) 
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N»RIDC:'L' ♦ BLKW 1 5 

N.RID : 'L ' . BLKB IB . i 

IM*RP3Cs ' L ' . BLK W 1 5 

N.RP3: 'L ' .BLKB 8. 5 

IM.RACC s ' L ' ♦ BLKW 1 5 

N*RAC5 'L' * B L K B 16. 5 

N * ROL= ' B ' ♦ -N ♦ RND 5 
. PSECT 

♦ENDM CRBDF* 
. MACRO CNBDF$ >L t 

tiif nb L S T * 
♦ ASECT 

. =0 

N . CTL : 'L' ♦ BLK W 1 5 

N * 3EGZ s 'L ' 4 BLKW 1 5 

N 4 DFM : 'L ' . BLKB 1 5 

N 4 DOT s 'L ' 4 BLKB 1 5 

4 BLKB 18. 5 

4=4-18. ; 

N . DDEC : ' L ' . BLKW 1 5 

N .DDE: 'L ' .BLKB IB. 5 

4=4-18. ; 

N . DGP : ' L ' ♦ BLK W 1 i 

N 4 DUB s 'L ' . BLKW 1 ? 

N 4 DNMC ; 'L ' ♦ BLK W 1 ? 

N 4 DNM s 'L ' .BLKB 12. ? 

N.3IMD: 'L' .BLKB S 5 

N . 3FM : 'L ' . BLKB 1 5 

N.SOTs 'L' ♦ BLKB 1 5 

♦ BLKB 18. 5 

4 = 4-184 ; 

N 4 3DEC : 'L ' .BLKW 1 ? 

N.3DE: 'L ' ♦ BLKB IB. 5 

,=4-i8, ; 

N 4 3GP : 'L ' ♦ BLKW 1 5 

N.3U3; 'L ' . BLKW 1 ! 

N.3NMC: 'L' 4 BLKW 1 5 

N . 3NM; 'L ' ♦ BLKB 12. 5 



R e q u e s t i n g process ID byte count 
Requesting process ID 
Requesting password byte cou n t 
Requesting password 
Accounting i n f o r m a t i o n byte c o u n t 
Accounting informatio n 

Length of block 



B >LST 
List 



T e lit p o r 


a r 


y I 


ink address 


S e g m e n 


t 


s i z 


e 


D e s t i n 


at 


i on 


descriptor format 


D e s t i n 


at 


i o n 


Object type 


Format 









U n u s e d 








Format 


1 






D e s t i n 


at 


i on 


process byte count 


D e s t i n 


at 


i on 


process 


F o r m a t 








D e s t i n 


a t 


i o n 


group 


D e s t i n 


at 


i on 


user 


D e s t i n 


at 


i on 


n a m e byte c o u n t 


D e s t i n 


at 


i on 


n a m e 


Source 


n 


ode 


n a m e 


Source 


d 


esc 


riptor format 


Source 





b J e 


c t type 


Format 









U n u s e d 








Format 


1 






Source 


p 


roc 


ess name byte count 


Source 


p 


roc 


ess name 


Format 








Source 


g 


r o u 


p 


Source 


U 


s e r 




Source 


n 


ame 


byte co u n t 


Source 


n 


ame 
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$$$= ( 








N ♦ C I DC 


: ' L ' 


♦ BLK W 


1 


N , C I D 5 


' L ' 


. BLKB 


1 G * 


N * CP3C 


s ' L ' 


♦ BLK W 


1 


N ♦ CP3 : 


' L ' 


♦ BLKB 


8 ♦ 


N * CACC 


: 'L ' 


« BLK W 


1 


N * CAC s 


'L ' 


. BLKB 


i 6 ♦ 


N . CDAC 


: ' L ' 


. BLK W 


i 


N. CDAs 


'L ' 






N ♦ CBL = 


' B ' ♦ 


-N . CTL 




, = $$$ 








N ♦ CDEv 


; ' L ' 


♦ BLK W 


1 


hi HI Ihl T 

N ♦ CUN I 


: ' L ' 


* BLK B 


1 






♦ E K 1 E N 




N * CU I C 


s ' L ' 


. BLKW 


1 






. P3ECT 




N ♦ CDD3 


s ' L ' 


♦ BLKB 


1 1 . 






♦ PSECT 





♦ENDM CNBDF* 



5 Source task ID byte count 
5 Source task ID " " 
5 Password byte c o u n t 
5 Password 

5 Accounting information byte c o u n 

5 Accounting informal i o n 

5 Optional data byte count 

5 Optional data 

5 

? Length of c n b (without a n y data) 

5 Default device name (from accoun 
5 Default device unit n u m b e r 

5 Login DIG from account file 

5 Default, directory string 
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E 

Network Error/Completion Codes for FORTRAN, 

COBOL, and BASIC-PLUS-2 



This appendix lists the error/completion codes that can be returned in the first word 
of any 2-word I/O status block by certain calls in the FORTRAN, COBOL, and 
BASIC-PLUS-2 languages. 

1 The request was successful. 

2 The request was successful, but some optional data was lost. 
-1 Required system resources are not available. 

-2 A request was issued for a LUN on which there is no established logical link. 

-3 The link was disconnected with the request outstanding. 

-4 The data received was truncated because the receive buffer was too small. 

-5 An argument specified in the call is incorrect. 

-6 No network data was found in the user's network data queue. 

-7 The network (NSP) rejected an attempted connect. 

-8 A logical link has already been established on the LUN to which the user attempted to 
connect. 

-9 The issuing task is not part of the network (that is, OPNNT was never called) . 

-10 The user is attempting to access the network for a second time. 

-11 Transmission of an interrupt message was attempted before the last one finished. 

-12 A connect reject was issued by the user task to which the connection was attempted. 

-13 A buffer either is outside the user address space or is not word aligned. 

-14 The user is attempting to issue a GNDNT[W] when one is already pending. 



E-1 



-20 A RUNNCW was issued for which there was not enough dynamic memory on the remote 
node. 

-21 A RUNNCW or ABONCW was issued for a task that was not installed on the remote 
node. 

-22 A RUNNCW was issued with an invalid time parameter. 

-23 Either an ABONCW was issued for a task that was not active, or a RUNNCW without 
scheduling parameters was issued for a task that already is active. 

-24 There was a privilege violation on a RUNNCW or ABONCW attempt. 

-25 An ABONCW was issued for a task that either was being loaded into or was exiting from 
the remote node. 

-26 An RUNNCW was issued with an invalid UIC. 

-40 A directive error; the second word of the status block contains the actual directive error 
code. 
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F 

Network MACRO-11 Error/Completion Codes 



Applicable Standard RSX Codes 

The following MACRO-11 error completion codes include all network related I/O 
error completion codes pertaining to this manual. These codes are defined in the 
IOERR$ macro in RSXMAC.SML, which is referenced in the NSSYM$ macro in 
NETLIB.MLB. 



Mnemonic 

IS.SUC 
IS.DAO 

IE. BAD 

IE.SPC 

IE.WLK 

IE.DAO 
IE.ABO 

IE.PRI 
IE.RSU 



Decimal 
Value 

1 
2 



-12 

-13 
-15 

-16 
-17 



Octal 

Value Meaning 

1 The request was successful. 

2 The request was successful, but some data 
was lost. 

377 Invalid buffer parameter, or data length 

exceeds 16. bytes. 

372 Invalid buffer parameters: buffer may not 

be word-aligned; buffer may be outside 
user address space; or buffer may exceed 
8128. bytes. 

364 Transmission of an interrupt message was 

attempted before the last one finished. 

363 Data overrun; unstored data is lost. 

361 The link was aborted or disconnected (see 

disconnect and reject reason codes, Appen- 
dix A.) 

360 The network is not accessed on this LUN. 

357 Required system resources are not avail- 

able. 



(continued on next page) 
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Decimal Octal 

Mnemonic Value Value 

IE.ALN -34 336 

IE.NLN -37 333 

IE.URJ -73 267 

IE.NRJ -74 266 

IE.NDA -78 262 

IE.NNT -94 242 



Meaning 



The specified LUN is already established. 

There is no established logical link on the 
specified LUN. 

The remote task rejected an attempted 
connection. 

The network rejected an attempted con- 
nection (see disconnect and reject reason 
codes, Appendix A). 

There is no data to return. 

The issuing task is not a network task; 
OPN$ was not executed successfully. 
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B 

BACC, 1-10, 3-3, 3-4, 3-6, 3-7, 

3- 8, 3-12, 3-16, 3-18, 3-22, 
3-125 

BACUSR, 3-125 
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3-14, 3-15, 3-22, 3-33 
BMFT1, 1-10, 3-3, 3-6, 3-7, 3-8, 

3-14, 3-17, 3-18, 3-19, 3-22, 

3-33 

Buffer space, 1-12, 2-32, 3-32, 
3-71, 3-72, 4-1, C-3,C-23 
Buffering level, 3-71 
BUILD type macro, 2-1, 2-2, 2-3 

c 

Closing files, 3-71 

Closing the network, 1-9, 3-2 

CLS$, 1-3, 1-5, 1-10, 2-6, 2-12, 

2- 37 

CLSNFW, 3-71, 3-84, 3-87, 3-91, 

3- 94, 3-98 
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CLSNT, 1-10, 3-2, 3-6, 3-37, 3-69, 

3-71, 3-121 
Completion status, 

see I/O status blocks 
CON$, 1-10, 2-6, 2-8, 2-14, 2-16, 

2-18, 2-24, 2-38, 2-39, 2-43, 

2-48 

CONB$$, 1-10, 2-6, 2-14, 2-16, 

2-18, 2-21, 2-23, 2-36 
Connect block, 1-2, 1-5, 1-6, 

1- 10, 2-6, 2-11, 2-14, 2-16, 

2- 17, 2-18, 2-23, 2-26, 2-31, 

2- 34, 2-36, 2-41, 3-12, 3-22, 

3- 27, 3-33 

Connect requests, 2-12, 2-38, 

3-21,3-39 
CONNT, 1-10, 3-2, 3-5, 3-6, 3-7, 

3-8, 3-9, 3-12,3-15,3-17, 

3-22, 3-23, 3-24, 3-25, 3-39, 

3-41,3-45,3-48 
Cyclic Redundancy Check (CRC), 

C-23, C-24 

D 

DAP (Data Access Protocol), B-l, 
B-2, C-2, C-4, C-5, C-7, C-8, 
C-10, C-12, C-15, C-24, C-26 
DDCMP, 4-1, 4-15, 4-20 
DECnet, 

code definitions, D-l 

communication calls ,1-10 

general description, 1-1 

macro library (NETLIB.MLB), 4-3 

message types, 1-7 

remote file access operations, 1-13 

task control, 1-14 

tasks, 1-6 
DELNFW, 3-70, 3-85 
Destination descriptor, 1-6, 2-18, 

2- 19, 3-6, 3-7, 3-8, 3-15, 

3- 22, D-2 
DIR$ macro, 2-2 

Disconnect or reject reason codes, 
A-l 

DLX (Direct Line Access Controller), 

general description, 4-1 
DLX calls, 

IO.XCL, 4-22 



DLX calls (Cont.) 

IO.XHG,4-21 

IO.XIN,4-12 

IO.XOP, 4-5 

IO.XRC, 4-17 

IO.XSC,4-8 

IO.XTM, 4-14 
DLX, 

QIOs, 4-1,4-3 
DLXBUF macro, 4-1, 4-14 
DSC$, 1-10, 2-6, 2-10, 2-14, 2-24 
DSCNT, 1-10, 3-6, 3-10, 3-22, 
3-25 

E 

Error/Completion codes, 2-9, 2-11, 
2-13, 2-15, 2-17, 2-25, 2-27, 
2-32, 2-38, 2-40, 2-42, 2-44, 

2- 46, 2-49,3-3,3-9,3-11, 

3- 21, 3-23, 3-24, 3-26, 3-28, 
3-37, 3-40, 3-42, 3-44, 3-46, 
3-49, 3-124, 3-129 

Error /Completion codes, 

FORTRAN,COBOL,BASIC-PLUS-2, E-l 

MACRO-ll,F-l 

remote file access, C-l 
Establishing a network task, 3-2 
Ethernet, 

devices, 4-2 

general description, 4-2 

using DLX QIOs, 4-4 
Event flags, 3-3, 3-71, 4-3 
EXECUTE type macro, 2-1, 2-2, 2-3, 
2-4 

EXENFW, 3-70, 3-86 

F 

FAL (File Access Listener), B-l, 

B-2, C-2 
Flow control, 

incoming messages, 2-11 

options, 1-12 

G 

GETNFW, 3-70, 3-87 

GLN$, 1-3, 1-5, 1-10, 2-6, 2-26, 

2-27, 2-37 
GLNNT, 1-10, 3-6, 3-27 
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GND$, 1-3, 1-5, 1-11, 2-5, 2-6, 
2-11, 2-14, 2-28, 2-30, 2-31, 
2-32, 2-34, 2-36, 2-37, 2-38, 

2- 41, 2-48,2-49 
GNDNT, 1-11, 1-12, 3-6, 3-10, 

3- 22, 3-29, 3-31, 3-32, 3-33, 
3-37, 3-39, 3-43, 3-48 

GND*, 1-7 



I/O status blocks, 3-2, 4-3 

Interrupt message, 
receiving, 2-49, 3-36 
sending, 1-2, 1-8, 2-6, 2-48, 
3-48 

Intertask communication, 
calls, 1-2, 2-6, 3-1, 3-3, 3-6, 

3-7 
concepts, 1-2 
conventions, 1-2 
macros, 2-6, 2-7 

L 

Libraries, 

MACRO-11 (NETLIB.MLB), 2-1,4-3 

NETFOR.OLB, 3-1 
Links, 

data, 4-2, 4-16 

logical, 1-5, 2-12, 2-38, 3-39 
Logical unit numbers (LUN), 

see Assigning logical unit numbers 

assigned to NS, 1-5 

M 

Maintenance Operation Protocol 

(MOP), 4-6, 4-17, 4-20 
MBXLU, 1-3, 2-37, 3-38 

N 

Network File Access Routines 

(NFARs), 3-71, 3-72, 3-81 
Network, 
data queue, 1-2, 1-3, 1-6, 1-7, 
1-9, 2-12, 2-28 
NOFLOW option, 1-12,2-11,2-16 



NS: pseudodevice driver, 2-9, 

2-11, 2-13, 2-17, 2-25, 2-27, 

2- 32, 2-37, 3-2, 3-38 
NSSYM$ macro, A-l, D-l, F-l 
NT.LON, 2-5, 2-28, 2-31, 2-32 
NT.TYP, 2-5, 2-28, 2-31, 2-32 

o 

Object type codes, 2-19, 3-15, 
B-l 

OPANFW, 3-70, 3-80, 3-90, 3-93, 

3- 94 
Open calls, 3-2 
Opening files, 3-70, 3-80 
OPMNFW, 3-87 

OPN$, 1-2, 1-3, 1-5, 1-H, 2-6, 

2- 9, 2-30, 2-37, 2-45 
OPNNT, 1-2, 1-11, 3-2, 3-6, 3-9, 

3- 11, 3-21, 3-24, 3-26, 3-28, 
3-37, 3-38, 3-42, 3-44, 3-46, 
3-49, 3-69, 3-121, 3-124, 
3-129 

OPRNFW, 3-70, 3-74, 3-75, 3-80, 

3-87, 3-90, 3-93 
OPUNFW, 3-87 

OPWNFW, 3-70, 3-80, 3-93, 3-94, 
3-97, 3-99 

P 

Parameters, 
for task build, 3-71 
overriding MACRO-1 1,2-1, 2-3 
required for MACRO-1 1 , 2-4 

PRGNFW, 3-71, 3-91, 3-93, 3-94, 
3-98 

PUTNFW, 3-70, 3-91, 3-94 

Q 

QIOs for DLX, 
see DLX 

R 

Reading a file, 1-1, 3-70, 3-87, 
3-90 

REC$, 1-11, 2-6, 2-10, 2-14, 2-39 
RECNT, 1-11, 3-6, 3-10, 3-22, 
3-41 
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Records, 

writing, 1-1, 3-94, 3-97 
REJ$, 1-3, 1-5, 1-11, 2-6, 2-14, 

2- 18, 2-37, 2-41 
Reject reason codes, 2-17, A-l 
REJNT, 1-11, 3-6, 3-22, 3-43 
Remote file access, 

argument definitions, 3-75 
buffer space, 3-72 
calls, 3-1, 3-2, 3-3 
closing files, 3-71 
concepts, 1-1, 1-13, 1-14 
opening files, 3-70 
task build parameters, 3-73 
Remote task control, 1-2, 1-14, 

3- 121 

s 

Scheduling a task for execution, 

1- 2, 1-14, 3-126 
Send an interrupt message, 

see Interrupt message 
Send data, 

seeSND$, SNDNT 
SND$, 1-11, 2-6, 2-10, 2-14, 2-43 
SNDNT, 1-11, 3-6, 3-10, 3-22, 
3-45 

Source descriptor, 1-5, 1-6, 2-34, 

3-34, D-3 
SPA$, 1-3, 1-5, 1-11, 2-6, 2-28, 

2- 37,2-45, 2-47 
SPLNFW, 3-70, 3-80, 3-93, 3-97, 

3- 98, 3-99 
Spool or print a file, 

see SPLNFW 
STACK type macro, 2-1, 2-4 
SUBNFW, 3-70, 3-80, 3-93, 3-97, 
3-98, 3-99 

T 

Task control block, 3-123, 3-127 
Task control utility, 3-121, B-l 
Task, 

scheduling, see RUNNCW 
see Intertask communication 
aborting, 
see ABONCW 



u 

User abort, / 
seeABT$, ABTNT, GND$, GNDNT 

User disconnect, 

seeDSC$, DSCNT, GND$, GNDNT 

w 

WAITNT, 1-11, 1-12, 3-6, 3-47 

X 

XMI$, 1-11, 2-6, 2-10, 2-14, 2-48 
XMINT, 1-11, 3-6, 3-10, 3-22, 
3-48 
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